我在Windows上使用Sphinx。
我的大部分文档都是针对普通用户的,但是有一些仅供pipe理员使用的内容。 所以我想build立我的文档的两个版本:一个完整的版本,第二个版本的“pipe理”页面排除在外。
我在构buildconfiguration中使用了exclude_patterns
。
到目前为止,它的工作。 当我把这个文件放入conf.py
文件时,每个子文件夹中名为“admin”的文件都被忽略:
exclude_patterns = ['**/*admin*']
问题是,我想运行一次构build,以获得两个版本。
我现在要做的是运行make.bat
两次,并在每次运行时提供不同的参数。
根据文档 ,我可以通过设置BUILDDIR
和SPHINXOPTS
variables来实现这一点。
所以现在我有一个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
时,两个不同目录中的构build工作。
但是,排除模式不起作用。
上面列出的batch file为第二个版本(带有排除模式的版本)输出这个文件:
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!
我究竟做错了什么?
sphinx-build
命令行中的exclude_patterns
语法与conf.py
文件中的语法不同?
还是有更好的方法来一步build立两个不同的版本?
我的第一个想法是这是一个引用问题,引用臭名昭着的difficule来正确的Windows命令行。 但是,我无法想出任何改变行为的引用组合。 (这个问题很容易复制)
当然,这可能还只是一些引用问题,我不够聪明,但我怀疑这是某种类型的狮身人面像缺陷,希望能够向狮身人面像开发者汇报。
同时,这里有一个替代方案:
从这里引用:
配置文件中有一个名为
tags
的特殊对象。 它可以用来查询和更改标签(请参阅包含基于标签的内容)。 使用tags.has('tag')
查询tags.add('tag')
和tags.remove('tag')
来更改
这允许您conf.py
将标志传递给conf.py
文件,由于conf.py
文件只是Python,因此可以使用if
语句根据传递的标记有条件地设置exclude_patterns
的值。
例如,你可以通过狮身人面像选项,如:
设置SPHINXOPTS = -t foradmins
通过“foradmins”标签,然后在你的conf.py
检查它是这样的:
exclude_patterns = blah if tags.has('foradmins'): exclude_patterns = []
这应该让你做你想做的。 祝你好运!