Transform `generate_reference` into a proper Sphinx extension

[mstimberg]

This will make it integrate better with the Sphinx build system.

[mstimberg]

The main idea behind this was to allow the detection of changed files to work properly, so that we don't re-generate the whole reference documentation at every documentation rebuild. This is not possible to achieve at the moment, though, as there is no point where we could hook into the process. We could do the generation at the setup of the extension, but at this point the environment is not prepared yet so we can't ask it about which source files changed -- running it there would therefore be the same as running it in conf.py (as we are doing currently). The next available signal is env-get-outdated but at this point sphinx already checked all the files so if we generate reference files now, they are not detected.

In the sphinxext_improvements branch, I nevertheless changed the system a bit so that it only writes files when they changed, so sphinx doesn't count these files as changed (the files are also no longer deleted in the beginning). This works fine and greatly increases the speed of the documentation generation, the only situation it does not handle is a reference file that should be removed -- such files do not do any harm, though, except for leading to a warning about an unreferenced file.

[thesamovar]

Ah that's nice - it was a bit annoying when writing docs to have to rebuild from scratch.

[mstimberg]

Yes, it's much faster now, even though it is by default running all the doctests included in the documentation (which we might split off at some point but currently we do not have that many, anyway). Note that the branch currently needs a patched version of sphinx to actually work correctly (fixing #18 ).