tkrajina/gpxpy

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:

  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

Done. Check out PR #212.