无法使用 Sphinx 可读性主题
Unable to use the Sphinx Readability theme
我想为我的 Sphinx 使用可读性主题，它可用 here。但是，当我按照说明中的建议通过修改我的 conf.py 文件来尝试使用此主题时，它在执行 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
我看到人们以前在报告的其他一些主题中遇到过类似的问题 in this question。但是，在我的例子中，conf.py 文件在那里。
更新
我尝试了 virtualenv 中的主题，以及较新的 sphinx。它在执行 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
所以我可以通过在上面应用 patch to sphinxtheme-readability. There is also a bug report 来解决这个问题。
配置：
我的 source/conf.py 看起来像这样：
import sphinxtheme
html_theme = 'readability'
html_theme_path = sphinxtheme.get_html_theme_path()
补丁：
这是我必须应用的补丁 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]
我还提交了 Pull Request 来解决这个问题。
您可以通过以下操作简单地进行测试：
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
解释： 你 运行 进入这个问题的原因以及我认为主题和它的示例配置有点破损的原因是因为路径完全错误。参见：
$ 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
注意我在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
我想为我的 Sphinx 使用可读性主题，它可用 here。但是，当我按照说明中的建议通过修改我的 conf.py 文件来尝试使用此主题时，它在执行 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
我看到人们以前在报告的其他一些主题中遇到过类似的问题 in this question。但是，在我的例子中，conf.py 文件在那里。
更新
我尝试了 virtualenv 中的主题，以及较新的 sphinx。它在执行 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
所以我可以通过在上面应用 patch to sphinxtheme-readability. There is also a bug report 来解决这个问题。
配置：
我的 source/conf.py 看起来像这样：
import sphinxtheme
html_theme = 'readability'
html_theme_path = sphinxtheme.get_html_theme_path()
补丁：
这是我必须应用的补丁 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]
我还提交了 Pull Request 来解决这个问题。
您可以通过以下操作简单地进行测试：
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
解释： 你 运行 进入这个问题的原因以及我认为主题和它的示例配置有点破损的原因是因为路径完全错误。参见：
$ 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
注意我在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