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

Question

我在Windows上使用Sphinx.
我的大多数文档都是针对普通用户的,但有一些子页面仅包含管理员的内容.所以我想构建我的文档的两个版本:完整版本和排除"管理"页面的第二个版本.

我exclude_patterns在构建配置中使用了它.
到目前为止,它的确有效.当我将其放入conf.py文件时,将忽略名称中包含"admin"的每个子文件夹中的每个文件:

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

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

我现在正在尝试做的是运行make.bat两次并在每次运行时提供不同的参数.
根据文档,我可以通过设置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

当我set BUILDDIR=build从sphinx生成的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开发者报告.

与此同时,这是另一种解决方案:

引自这里:

tags配置文件中有一个名为available 的特殊对象.它可用于查询和更改标记(请参阅包含基于标记的内容).使用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 = []

这应该可以让你做你想做的事.祝好运!