Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RDY] Project documentation #302

Merged
merged 27 commits into from Mar 4, 2018
Merged

[RDY] Project documentation #302

merged 27 commits into from Mar 4, 2018

Conversation

stsewd
Copy link
Contributor

@stsewd stsewd commented Feb 3, 2018

Hi, this is an initial proposal to add the project documentation using sphinx, later we could host the docs on https://readthedocs.org/ so it gets updated on each commit.

This is an example of how it looks

screenshot-2018-2-3 neovim class neovim documentation

Please let me know if you are agree with this, so I can keep with this PR :). Thanks for so awesome API!

@justinmk
Copy link
Member

justinmk commented Feb 9, 2018

Nice. Can you write the prerequisites needed to run this? Maybe it should be added to CI ?

@stsewd
Copy link
Contributor Author

stsewd commented Feb 25, 2018

@justinmk sorry for the late reply, I added the docs env to tox. I'll be writing the docs on the next days/weeks :)

@stsewd
Copy link
Contributor Author

stsewd commented Feb 25, 2018

@justinmk this is how it would looks like on rtd http://stsewd-test-nvim-python-client.readthedocs.io/en/latest/index.html (just for testing, I'll delete the project once the PR is merged).

docs/index.rst Outdated
@@ -1,5 +1,5 @@
Neovim's Python Client
======================
Neovims Python Client
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this must be Neovim as well? (without s)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now I fixed it 😄

@stsewd stsewd changed the title Project documentation [WIP] Project documentation Feb 25, 2018
@stsewd
Copy link
Contributor Author

stsewd commented Feb 25, 2018

Please feel free to correct me any grammatical error or misspelling, since English isn't my native language.

Also I'm following the rtd style guide for docs here.

@justinmk
Copy link
Member

justinmk commented Feb 27, 2018

LGTM. I don't think we need 19 commits of granularity, I'll squash to 1 unless there are a couple changes you think need to be separated in the history.

Is this still WIP or ready to go?

What happens next? Do we need to register on RTD website (hope not), or will it pick up the .readthedocs.yml somehow?

@@ -0,0 +1,7 @@
Neovim Class
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't this be "Nvim Class"?

docs/conf.py Outdated

# General information about the project.
project = 'Neovim Python Client'
copyright = '2018, Neovim'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

probably should be 2014

@stsewd
Copy link
Contributor Author

stsewd commented Mar 4, 2018

LGTM. I don't think we need 19 commits of granularity, I'll squash to 1 unless there are a couple changes you think need to be separated in the history.

Yeah, one commit is fine for me too (sorry, I do every little separate change a commit).

Is this still WIP or ready to go?

Yes, it is still WIP, just need to finish two or three sections.

What happens next? Do we need to register on RTD website (hope not), or will it pick up the .readthedocs.yml somehow?

Yes, someone with access to the repository must be registered on RTD (if not, you can't configure the webhook), then:

  • Link the github account to RTD (optional)
  • Import the project from the RTD page.
    • Be careful when choosing the name, that would be the url of the docs and can't be changed, if you choose Neovim Python Client, the url is neovim-python-clien.readthedocs.io.
  • Setup the webhook (this is done automatically if you opt for the first step)
  • That's all! With every push to master, the docs get updated!

After that we can include the RTD badge on the readme file and probably.

Sorry for the late reply, again.

@stsewd stsewd changed the title [WIP] Project documentation [RDY] Project documentation Mar 4, 2018
@stsewd
Copy link
Contributor Author

stsewd commented Mar 4, 2018

@justinmk I think we are ready to go now, please let me know any problem and I will try to fix it the faster that I can. Thank guys, I really appreciate all the work you do on Neovim.

@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

I signed up on RTD, and seem to be able to connect the project. Quite a bit of text in README.md is duplicated, I suppose we want to change it to RTD links once it is up and running

@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

Be careful when choosing the name, that would be the url of the docs and can't be changed

@justinmk Maybe this is the time to change the name of the library to pynvim?

@stsewd
Copy link
Contributor Author

stsewd commented Mar 4, 2018

@bfredl Yeah, I was thinking the same, it's probably better to keep a simpler readme file and just linking from that to RTD. A PR after this one is merged is better (so we can include the rtd badge too!)

tox.ini Outdated
@@ -1,5 +1,7 @@
[tox]
envlist = py{27,33,34,35,36}-{asyncio,pyuv},pypy
envlist =
py{27,33,34,35,36}-{asyncio,pyuv},pypy
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

py33 should be removed

Installation
============

The Neovim Python client supports Python 2.7, and 3.3 or later.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3.4

@bfredl bfredl merged commit 9767ffe into neovim:master Mar 4, 2018
@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

LGTM, merged. Thanks for your work!

@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

http://pynvim.readthedocs.io/en/latest/ seems to work.

However, Readthedocs at the same time claims that it did create a GitHub webhook, and that there is no working webhooks, so automatic updates are disabled.

@stsewd stsewd deleted the docs branch March 4, 2018 08:34
@justinmk
Copy link
Member

justinmk commented Mar 4, 2018

Good call. Could be interesting to do this for the vim docs ....

@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

@justinmk as project admin I think you have to go to the settings page of this repo and somehow accept the readthedocs hook, or you could give me the right to manage hooks for this repo :)

@stsewd
Copy link
Contributor Author

stsewd commented Mar 4, 2018

@bfredl Yes, you need rights to create webhooks on the repo to RTD be able to do it, also you could include @justinmk as maintainer on RTD (the webhook setting now needs to be do it manually, just copying a url).

@justinmk
Copy link
Member

justinmk commented Mar 4, 2018

The generated docs should be linked in the README.md (and any duplicate content should be removed). In the meantime I added http://pynvim.readthedocs.io/en/latest/ to the repo description.

@bfredl
Copy link
Member

bfredl commented Mar 4, 2018

@stsewd It should be fixed now, I pushed commit and its seems the hook was triggered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants