6

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

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

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

我究竟做错了什么？命令行中
的语法与文件中的语法不同吗？ 或者有没有更好的方法来一步构建两个不同的版本？exclude_patternssphinx-buildconf.py

4

1 回答 1

10

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

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

与此同时，这是一个替代解决方案：

从这里引用：

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

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

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

为管理员设置 SPHINXOPTS=-t

传递“foradmins”标签，然后conf.py像这样检查它：

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

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

于 2012-12-07T15:27:44.710 回答