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

Build Sphinx documentation and host on ReadTheDocs #211

Open
JWCook opened this issue Nov 22, 2020 · 3 comments · May be fixed by #212
Open

Build Sphinx documentation and host on ReadTheDocs #211

JWCook opened this issue Nov 22, 2020 · 3 comments · May be fixed by #212

Comments

@JWCook
Copy link

JWCook commented Nov 22, 2020

It would be helpful to have HTML documentation for gpxpy. It appears that the source code is the main source of documentation currently.

Since gpxpy already has type annotations and some docstrings, it would be fairly simple to use sphinx-apidoc and sphinx-autodoc-typehints to generate HTML docs using the information that's already present.

I would be willing to set this up, if you'd be open to a PR for this.

@tkrajina
Copy link
Owner

I'm not familiar with sphing, how would that work. Once it's done, will the docs on reaththedocs automatically change? Do I need to setup some hooks on this repo or I need to reload something when I publish new releases?

I'm all for having better/nicer documentation, but before deciding I'd like to know if it also implies some additional complexities/work for me in the future :)

@JWCook
Copy link
Author

JWCook commented Dec 21, 2020

Yes, building and publishing docs would be automatic. It does require a hook for ReadTheDocs, but the rest is just code & config. After setup, there isn't much maintenance required. The main pieces are:

  1. Python docstrings for your public API (already done)
  2. Sphinx plugins + configuration that takes your docstrings and generates reStructuredText (.rst) files
  3. Sphinx build configuration that takes these .rst files and generates HTML documentation
  4. An account on ReadTheDocs that watches your GitHub repo and builds & publishes docs (typically, whenever a new commit is pushed to either the dev or master branch)

I can contribute the Sphinx config, so all you need to do is step 4.

You can also add a ReadTheDocs badge to your README, if you'd like.
More introductory info here: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

@JWCook JWCook linked a pull request Dec 21, 2020 that will close this issue
@JWCook
Copy link
Author

JWCook commented Dec 21, 2020

Done. Check out PR #212.

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 a pull request may close this issue.

2 participants