Unable to use the Sphinx Readability theme

Question

I want to use the Readability theme for my Sphinx, which is available here. However, when I tried to use this theme by modifying my conf.py file as suggested in the instructions, it shows this error when doing make html:

sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.3.1
loading pickled environment... done

Theme error:
no theme named 'readability' found (missing theme.conf?)
make: *** [html] Error 1

I see that people have had problems like this before with some other themes as reported in this question. However, in my case the conf.py file is present there.

UPDATE

I tried the theme inside a virtualenv, with a newer sphinx. And it shows this error when doing make html:

sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.3.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index

generating indices... genindex
Exception occurred:
  File "~/DEVEL/python/sphinx/sphinx2/local/lib/python2.7/site-packages/sphinx/jinja2glue.py", line 159, in get_source
    raise TemplateNotFound(template)
TemplateNotFound: readability/layout.html
The full traceback has been saved in /tmp/sphinx-err-q42_PH.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 1

Answer 1

So I was able to fix this by applying a patch to sphinxtheme-readability. There is also a bug report on this.

Configuration:

My source/conf.py looks like this:

import sphinxtheme

html_theme = 'readability'
html_theme_path = sphinxtheme.get_html_theme_path()

Patch:

This is the patch I had to apply to sphinxtheme/__init__.py:

diff --git a/sphinxtheme/__init__.py b/sphinxtheme/__init__.py
index b0d6433..a3edbe0 100644
--- a/sphinxtheme/__init__.py
+++ b/sphinxtheme/__init__.py
@@ -1 +1,7 @@
-__import__('pkg_resources').declare_namespace(__name__)
\ No newline at end of file
+import os
+
+
+def get_html_theme_path():
+    """Return list of HTML theme paths."""
+    cur_dir = os.path.abspath(os.path.dirname(__file__))
+    return [cur_dir]

---

• My Fork of sphinxtheme-readability
• My Test of sphinxtheme-readability
  • Demo

I've also submitted a Pull Request to address this issue.

You can test this out simply by doing:

mkvirtualenv test-sphinxtheme-readability
git clone https://github.com/prologic/test-sphinxtheme-readability.git
cd test-sphinxtheme-readability
pip install -r requirements.txt
make clean html
circuits.web build/html

And visit: http://localhsot:8000/

---

Explanation: The reason you ran into this issue and where I believe the theme and it's sample configuration is a little broken is because the path is quite wrong. See:

$ make clean html
rm -rf build/*
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.3.1
making output directory...
readability_path:  /home/prologic/.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme
relative_path:  ../../../.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                         
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                          
generating indices... genindex
Exception occurred:
  File "/home/prologic/.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinx/jinja2glue.py", line 159, in get_source
    raise TemplateNotFound(template)
TemplateNotFound: readability/layout.html
The full traceback has been saved in /tmp/sphinx-err-8zoG8h.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:55: recipe for target 'html' failed
make: *** [html] Error 1

$ ls -lah /home/prologic/.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme
total 32K
drwxr-xr-x  3 prologic users 4.0K Jun 15 09:30 .
drwxr-xr-x 37 prologic users 4.0K Jun 15 09:30 ..
-rw-r--r--  1 prologic users   55 Jun 15 09:30 __init__.py
-rw-r--r--  1 prologic users  243 Jun 15 09:30 __init__.pyc
drwxr-xr-x  3 prologic users 4.0K Jun 15 09:30 readability
-rw-r--r--  1 prologic users 5.6K Jun 15 09:30 readability_theme_support.py
-rw-r--r--  1 prologic users 2.8K Jun 15 09:30 readability_theme_support.pyc

$ ls -lah ../../../.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme
ls: cannot access ../../../.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme: No such file or directory

Note the two paths that I printed in source/conf.py:

readability_path:  /home/prologic/.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme
relative_path:  ../../../.virtualenvs/sphinx-readability/lib/python2.7/site-packages/sphinxtheme