Readthedocs autodocs do not work #1197

Merged
merged 2 commits into from Aug 21, 2013

Conversation

Projects
None yet
3 participants
Contributor

domoritz commented Aug 19, 2013

Copied from okfn#978 (comment)

@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.

Contributor

domoritz commented Aug 19, 2013

I think we should add a new requirements file that installs the requirements and the dev requirements. This way, we only have to maintain two requirements files. There is probably no way around naming it pip-requirements-docs.txt since rtd requires the same file for every version.

Contributor

domoritz commented Aug 19, 2013

I'm confused. I changed the requirements for for rtd back to pip-requirements-docs.txt and hit rebuild. However, neither the 2.0.2 docs, nor the docs for this branch work. Any ideas?

Contributor

domoritz commented Aug 19, 2013

Okay, status:

  • 2.0.2 auto docs
  • 2.0.2 search
  • this branch auto docs
  • this branch search (I guess this is because the index is being rebuilt)

@amercader amercader merged commit 5c53694 into master Aug 21, 2013

1 check passed

default The Travis CI build passed
Details

@amercader amercader added a commit that referenced this pull request Aug 21, 2013

@amercader amercader [#1197] Downgrade Sphinx to fix search on RTD
There is a bug on RTD that prevents the search when using Sphinx 1.2b1.

All details here:

rtfd/readthedocs.org#443
f4306ee
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment