Sphinx for Read the Docs #87
Conversation
|
How do we keep the version in docs/conf.py:release in sync with the one in pandas_vet.version? |
mostly defaults from the example, but does have requirements set.
This isn't the final location of the API docs, but it's proof of concept.
post-merge of deppen8#88
|
We need to decide how to handle docs building. Can someone push to a branch in this repo without giving them access to Otherwise, there might be some intervention by the RTD team that could turn on a feature flag that would allow us to build from PRs or some other source. |
|
The Read the Docs feature flag is Which really is probably what you want long-term. This particular branch is going to be especially heavy on sphinx-config-twiddling, but in general, you'll still want the option of making sure the RTD build works with future PRs... The "use the rtd.org Update: this is better documentation about it: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html |
|
On the GitHub side, there's branch protection to enabled a collaborator to fiddle with a side branch in the main repo without being able to push to a release branch. I think. It's a little hard to tell just from the docs which options are available to which repos. It might be different if the repo is owned by an individual or an Organization? probably the way to find out is to add a collaborator you trust and then see which options it gives you. |
autodoc vs autoapiautodoc is the standard, shipped with sphinx. The distinguishing feature of autoapi is that it parses the source, instead of importing (evaluating) it as autodoc does. That sort of distinction will be familiar to the sort of people who work on linters. Is there much practical difference on this repository, as small as it is? Not sure. |
Since we're only documenting one module, we don't need the list of modules.
the same way setup.py does it.
Doesn't deploy them, just makes sure they build. Maybe redundant if Read the Docs has sufficient github integraion on pull requests.
|
Okay, as far as the build process goes, things are looking pretty good on this end. Still need to confirm the RTD build server feels the same way. Aside from that, the remaining work is all about content! |
docs/Makefile and docs/make.bat were created by sphinx-quickstart. The Makefile, however, doesn't have any real targets or build rules in it, it's just a passthrough to If this project has any other convention for providing shortcuts to build commands (e.g. shell scripts, distutils commands, some other build system, or IDE-based launchers), we could use that instead and then people wouldn't stop to wonder “What is a |
not sure why it fails these. linkcheck needs better diagnostic output.
|
the linkcheck fail is because GitHub gets tricky when rendering embedded markdown. See sphinx-doc/sphinx#6779 |
For #70
Pages for