Error message “no theme named 'sphinx-theme-okfn'” when trying to build CKAN's docs

Question

I have CKAN installed in a virtualenv and the virtualenv activated, and I've installed the requirements in pip-requirements-docs.txt, but when I try to build the docs I get this error:

> python setup.py build_sphinx
...
sphinx.errors.ThemeError: no theme named 'sphinx-theme-okfn' found (missing theme.conf?)

Answer 1

The problem is that the Sphinx theme that CKAN uses is not part of the CKAN git repository itself, it has its own git repo which is a submodule of the CKAN git repo. So before you can build the docs, you need to checkout the submodule:

> git submodule init
> git submodule update
> python setup.py build_sphinx

Answer 2

I tried the above solution several times. I even upgraded Babel and Pygments and tried again - to no avail. The same error all the time. Finally I copied a file named theme.conf from https://github.com/rostock/opendata.hro/tree/master/ckan/doc/_themes/sphinx-theme-okfn to directory ~/ckan/default/src/ckan/doc/_themes/sphinx-theme-okfn; thus I was able to run sphinx somehow and to generate readable documentation for my CKAN 1.8 on Windows. Maybe my workaround will be of use to somebody?