rtd-build and readthedocs.yml specification

[gregmuellegger]

I've wrote something down on how I imagine rtd-build to work and how the readthedocs.yml file should look like.

It's open for discussion.

[takluyver]

Is it possible to have some key in the config for custom commands to be run before the docs build? Our docs often have things like Jupyter notebooks converted to rst, or autogenerated config docs, where we really want to do something before launching Sphinx. We can hack this by doing what we need from the Sphinx conf.py file (like this), but it's rather ugly.

[agjohnson]

We don't like this approach -- arbitrary command execution -- but we haven't yet ruled it out. You can indeed fake it with conf.py overrides, but we're hoping to eventually move folks away from even requiring conf.py for the majority of cases.

[takluyver]

You can also achieve it by doing stuff from setup.py, or by publishing crafted packages and then requiring those for the RTD build. Or even, if you were getting devious, by using autodoc and having code that runs on import.

It's not really practical to prevent arbitrary command execution, and it can be really useful (or we wouldn't fiddle around to do it from conf.py). So it would be nice to have a clear, simple way to do it.

[agjohnson]

When I say move away from arbitrary execution, I mean move away :)

We've been laying some work down with https://github.com/rtfd/sphinx-autoapi to create an autodoc feature for multiple languages. Currently, .NET is supported, and py2 is supported through epydoc. The python support is deficient at the moment, because epydoc is not maintained and does not support python 3. We have plans to fix all of this in some fashion though, and will eventually have a mostly drop in replacement for autodoc.

Ultimately, what this means for a Python developer writing API reference documentation, is that code will no longer be executed to inspect docstrings, it will be parsed. This will remove all need for installing dependencies outside documentation dependencies, doesn't require mocking or other conf.py hacks, and will reduce build times to a fraction of what they are now. The current standard for extracting docstrings is quite silly, really.

But there are plenty of other use cases, yours included, that require arbitrary command execution for documentation generation. So it's not something we feel we can ever avoid, and we might need to have a usable solution for. We would like it to be the edge case though, with the majority of Python users supported through code parsing.

[takluyver]

Doing something like autodoc without needing to execute code would be really nice for various reasons - e.g. we have some code that relies on PyQt, which we can't easily install or mock out on RTD, so we have to host the docs elsewhere. Getting docstrings just by parsing the source code would eliminate that problem.

In a few cases, we also have docstrings which are built dynamically (i.e. by setting foo.__doc__); clearly those can't be found by static analysis. However, that is definitely a small fraction of our docstrings.

Perhaps you could have something like Travis' sudo: required flag, e.g. execution: true, where builds that need to execute pre-Sphinx steps, use custom Sphinx extensions, etc. go in a separate build queue which may take longer?