Question

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.

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.

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.

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

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

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?

Answer 1

My first thought was that this was a quoting issue, quoting being notoriously difficult 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)

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.

In the meantime, here’s an alternate solution:

quoting from 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

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.

For example, you could pass Sphinx options like:

set SPHINXOPTS=-t foradmins

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!