如何从命令行设置Sphinx的`exclude_patterns`？ [英] How to set Sphinx's `exclude_patterns` from the command line?

问题描述

我在Windows上使用Sphinx。

我的大部分文档都是针对常规用户，但是有些子页面仅包含管理员的内容。
所以我想建立两个版本的文档：一个完整​​的版本，第二个版本的admin页被排除在外。

I'm using Sphinx on Windows.
Most of my documentation is for regular users, but there are some sub-pages with content for administrators only. So I want to build two versions of my documentation: a complete version, and a second version with the "admin" pages excluded.

构建配置中的href =http://sphinx-doc.org/config.html#general-configuration =nofollow> exclude_patterns 为此，

到目前为止，它的工作原理。当将这个文件放入 conf.py 文件中时，其名称中包含admin的每个子文件夹中的每个文件都将被忽略：

I used the exclude_patterns in the build configuration for that.
So far, it works. Every file in every subfolder whose name contains "admin" is ignored when I put this into the conf.py file:

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

问题是我希望运行一次以获取这两个版本。

The problem is that I'd like to run the build once to get both versions.

我正在努力做什么现在运行 make.bat 两次，并在每次运行时提供不同的参数。

根据文档，我可以通过设置 BUILDDIR 和 SPHINXOPTS 变量。

What I'm trying to do right now is running make.bat twice and supply different parameters on each run.
According to the documentation, I can achieve this by setting the BUILDDIR and SPHINXOPTS variables.

所以现在我有一个 build.bat 这个：

So now I have a build.bat that looks like this:

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 文件中设置BUILDDIR = build 。

The build in the two different directories works when I delete the line set BUILDDIR=build from the sphinx-generated make.bat file.

但是，排除模式不工作。

上面列出的批处理文件输出了第二个构建（具有排除模式的文件）：

However, the exclude pattern does not work.
The batch file listed above outputs this for the second build (the one with the exclude pattern):

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 文件中的

或有一个更好的方法来建立两个不同的版本吗？

What am I doing wrong?
Is the syntax for exclude_patterns in the sphinx-build command line different than in the conf.py file?
Or is there a better way to build two different versions in one step?

推荐答案

我的第一个想法是，这是一个引人注目的问题，引用在Windows命令行上的恶名昭彰。但是，我根本无法提出改变行为的任何组合。 （问题很容易复制）

My first thought was that this was a quoting issue, quoting being notoriously difficule to get right on the Windows command line. However, I wasn't able to come up with any combination of quoting that changed the behavior at all. (the problem is easy to replicate)

当然这还可能是一些引人入胜的问题，我不够聪明，但我怀疑这是一个狮身人面像一些bug，希望你能向Sphinx开发者报告。

Of course it could still just be some quoting issue I'm not smart enough to figure out, but I suspect this is a Sphinx bug of some kind, and hope you will report it to the Sphinx developers.

同时，这里有一个替代解决方案：

从这里：

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

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，你可以使用如果语句根据您传入的标签有条件地设置 exclude_patterns 的值。

This allows you to essentially pass flags into the conf.py file from the command line, and since the conf.py file is just Python, you can use if statements to set the value of exclude_patterns conditionally based on the tags you pass in.

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

For example, you could pass Sphinx options like:

设置SPHINXOPTS = -t foradmins

set SPHINXOPTS=-t foradmins

传递foradmins标签，然后在 conf.py 像这样：

to pass the "foradmins" tag, and then check for it in your conf.py like so:

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

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

That should allow you to do what you want. Good Luck!

这篇关于如何从命令行设置Sphinx的`exclude_patterns`？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！