Build Sphinx documentation and host on ReadTheDocs
JWCook opened this issue · 3 comments
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.
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 :)
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:
- Python docstrings for your public API (already done)
- Sphinx plugins + configuration that takes your docstrings and generates reStructuredText (
.rst
) files - Sphinx build configuration that takes these
.rst
files and generates HTML documentation - An account on ReadTheDocs that watches your GitHub repo and builds & publishes docs (typically, whenever a new commit is pushed to either the
dev
ormaster
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