Question

我在Windows上使用Sphinx 我的大多数文档都是针对普通用户的，但有一些子页面仅包含管理员的内容。所以我想构建两个版本的文档：一个完整版本，另一个版本不包含“admin”页面。

我使用了exclude_patterns in the build configuration 到目前为止，它的确有效。当我将其放入conf.py文件时，将忽略名称中包含“admin”的每个子文件夹中的每个文件：

exclude_patterns = ['**/*admin*']

问题是，我想运行构建一次来获取两个版本。

我现在要做的是运行make.bat两次，并在每次运行时提供不同的参数根据{{3}}，我可以通过设置BUILDDIR和SPHINXOPTS变量来实现此目的。

所以现在我有build.bat看起来像这样：

path=%path%;c:\python27\scripts

rem BUILD ADMIN DOCS
set SPHINXOPTS=
set BUILDDIR=c:\build\admin
call make clean
call make html

rem BUILD USER DOCS
set SPHINXOPTS=-D exclude_patterns=['**/*admin*']
set BUILDDIR=c:\build\user
call make clean
call make html

pause

当我从sphinx生成的set BUILDDIR=build文件中删除行make.bat时，两个不同目录中的构建工作正常。

但是，排除模式不工作上面列出的批处理文件为第二个版本（具有排除模式的版本）输出：

Making output directory...
Running Sphinx v1.1.3
loading translations [de]... done
loading pickled environment... not yet created

Exception occurred:
  File "C:\Python27\lib\site-packages\sphinx-1.1.3-py2.7.egg\sphinx\environment.
py", line 495, in find_files
    ['**/' + d for d in config.exclude_dirnames] +
TypeError: coercing to Unicode: need string or buffer, list found
The full traceback has been saved in c:\users\myusername\appdata\local\temp\sphinx-err-kmihxk.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.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

我做错了什么？ exclude_patterns命令行中sphinx-build的语法是否与conf.py文件中的语法不同？或者，是否有更好的方法可以一步构建两个不同的版本？

Answer 1

我的第一个想法是，这是一个引用问题，引用着名的难以在Windows命令行上运行。但是，我无法想出任何改变行为的引用组合。（问题很容易复制）

当然它可能只是一些引用问题我不够聪明，但我怀疑这是某种Sphinx漏洞，希望你能向Sphinx开发者报告。

与此同时，这是另一种解决方案：

引自here：

配置文件中有一个名为tags的特殊对象。它可用于查询和更改标记（请参阅包含基于标记的内容）。使用tags.has('tag')查询，tags.add('tag')和tags.remove('tag')进行更改

这允许您基本上从命令行将标志传递到conf.py文件，并且由于conf.py文件只是Python，您可以使用if语句来设置值exclude_patterns有条件地基于您传入的代码。

例如，您可以传递Sphinx选项，如：

设置SPHINXOPTS = -t foradmins

传递“foradmins”标记，然后在conf.py中检查它，如下所示：

exclude_patterns = blah
if tags.has('foradmins'):
    exclude_patterns = []

这应该可以让你做你想做的事。祝你好运！

如何从命令行设置Sphinx的`exclude_patterns`？

1 个答案: