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

Question

我在 Windows 上使用 Sphinx。
我的大部分文档都是针对普通用户的，但也有一些子页面的内容仅供管理员使用。所以我想构建我的文档的两个版本:一个完整​​版本和一个排除了“管理”页面的第二个版本。

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

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

问题是我想运行构建一次以获得两个版本。

我现在要做的是运行 make.bat 两次并在每次运行时提供不同的参数。
根据the documentation ，我可以通过设置 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 生成的 make.bat 文件中删除行 set BUILDDIR=build 时，两个不同目录中的构建工作。

但是，排除模式不起作用。
上面列出的批处理文件为第二个构建(具有排除模式的那个)输出这个:

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

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

Answer 1

我的第一个想法是这是一个引用问题，众所周知，在 Windows 命令行上引用很难正确。但是，我无法想出任何改变行为的引用组合。 (该问题很容易复现)

当然，它仍然可能只是一些引用问题，我不够聪明，无法弄清楚，但我怀疑这是某种 Sphinx 错误，希望您将其报告给 Sphinx 开发人员。

与此同时，这里有一个替代解决方案:

引自here :

There is a special object named tags available in the config file. It can be used to query and change the tags (see Including content based on tags). Use tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to change

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

例如，您可以像这样传递 Sphinx 选项:

set SPHINXOPTS=-t foradmins

传递“foradmins”标签，然后在您的 conf.py 中检查它，如下所示:

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

这应该允许你做你想做的事。祝你好运!