okfn/ckan — pull request #1197 by domoritz (2013-08-19 09:28:33+00:00)
Title: Readthedocs autodocs do not work

Copied from https://github.com/okfn/ckan/pull/978#issuecomment-22650690

@vitorbaptista @domoritz @amercader More issues due to renaming the requirements files, turns out this is the reason why our docs build is broken on readthedocs. Two problems:

RTD lets you specify a pip requirements file in your project config that it should install (in a virtualenv) before it tries to build the docs. It's not possible to tell it different requirements files for different branches or versions of the project. So the docs for CKAN versions 2.0 and older will always be broken, since the requirements file was renamed in CKAN 2.1.

I can't think of any way to fix this, even if we added the pip-requirements-docs.txt file that previous versions of CKAN had back, CKAN 2.1 has already been released without this file, so there may be no way to get all versions of the docs building successfully at once!

I think we may need to add pip-requirements-docs.txt back in CKAN 2.2, and backport this to 2.1.1.

Previously the pip-requirements-docs.txt file depended on the pip-requirements.txt file: https://github.com/okfn/ckan/blob/release-v2.0.2/pip-requirements-docs.txt

Now, pip-requirements-docs.txt was removed and its contents were moved into dev-requirements.txt which does not depend on requirements.txt. I changed our RTD config to use dev-requirements.txt instead of pip-requirements-docs.txt. But now the stuff in requirements.txt doesn't get installed, and so the docs build crashes: https://readthedocs.org/builds/ckan/747725/ (lots of no module named foo errors). This is why autodoc stuff (like the API reference docs, and lots of other things in the docs as well) is not working on RTD.

Can we just make dev-requirements.txt depend on requirements.txt, like pip-requirements-docs.txt used to? (Or if we're adding pip-requirements-docs.txt back to fix issue 1, then make it depend on requirements.txt like it used to.)

So in summary I think we need pip-requirements-docs.txt back with the stuff needed to build the docs plus depending on requirements.txt, exactly like it used to be, and we need to backport this to 2.1.1.