Allow sphinx to build with multiple source directories and watch for changes.
Project description
Build sphinx documentation from multiple source directories. Also includes an automatic build on change feature. This works by symlinking all the input directories to a single temporary directory and then running sphinx on that temporary directory.
Should work on Python >= 2.7, Linux and Windows Vista or later.
How to install
You can use pip install to install the package: pip install sphinx-multibuild
How to use from command line
Output of the –help command:
usage: sphinx_multibuild.py [-h] -i INPUTDIRS -s TEMPDIR -o OUTPUTDIR [-q] [-m] [-b builder] [-M makebuilder] [-a] [-E] [-d path] [-j N] [-c path] [-C] [-D setting=value] [-t tag] [-A name=value] [-n] [-v] [-Q] [-w file] [-W] [-T] [-N] [-P] [filenames [filenames ...]] Build multiple sphinx documentation directories into a single document. Also supports automatic build on change. Sphinx options arguments are passed through. positional arguments: filenames See \`sphinx-build -h\` optional arguments: -h, --help show this help message and exit -i INPUTDIRS, --inputdir INPUTDIRS One or more input directories. -s TEMPDIR, --symlinkdir TEMPDIR Temporary directory where symlinks are placed. -o OUTPUTDIR, --outputdir OUTPUTDIR The directory where you want the output to be placed -q, --quiet Only print warnings and errors. -m, --monitor Monitor for changes and autobuild -b builder See \`sphinx-build -h\` -M makebuilder See \`sphinx-build -h\` -a See \`sphinx-build -h\` -E See \`sphinx-build -h\` -d path See \`sphinx-build -h\` -j N See \`sphinx-build -h\` -c path See \`sphinx-build -h\` -C See \`sphinx-build -h\` -D <setting=value> See \`sphinx-build -h\` -t tag See \`sphinx-build -h\` -A <name=value> See \`sphinx-build -h\` -n See \`sphinx-build -h\` -v See \`sphinx-build -h\` -Q See \`sphinx-build -h\` -w files See \`sphinx-build -h\` -W See \`sphinx-build -h\` -T See \`sphinx-build -h\` -N See \`sphinx-build -h\` -P See \`sphinx-build -h\`
Sphinx options are available and are passed through to sphinx builder. The exception are the in- and output directories since those are used arguments to sphinx-multibuild itself. The -i specifies an input and can be repeated multiple times. The -s options specifies the temporary directory where symlinks are placed and the -o options sets the sphinx output directory.
Here is an example of building a document with multiple two input directories:
sphinx-multibuild -i ../doc -i ./build/doc/apigen -s ./build/doc/tmp -o ./build/doc/sphinx -b html -c ./build/doc/sphinx
Here is another example where the -M builder is used to build latexpdf in a single step.
sphinx-multibuild -i ../doc -i ./build/doc/apigen -s ./build/doc/tmp -o ./build/doc/sphinx -M latexpdf -c ./build/doc/sphinx
Using the -m option will continously build the output when anything changes in any of the input directories.
sphinx-multibuild -m -i ../doc -i ./build/doc/apigen -s ./build/doc/tmp -o ./build/doc/sphinx -b html -c ./build/doc/sphinx
How to use as module
It is also possible to use it as a module and control the building programmatically. There is a single class SphinxMultiBuilder that you can instantiate and create builds or automatically build:
from sphinx_multibuild import SphinxMultiBuilder
import logging
import time
import sys
# Package respects loglevel set by application. Info prints out change events
# in input directories and warning prints exception that occur during symlink
# creation/deletion.
loglevel = logging.INFO
logging.basicConfig(format='%(message)s', level=loglevel)
# You can register a handler that will be called when a symlink
# Can't be created or deleted.
def handle_autobuild_error(input_path, exception):
pass
# Instantiate multi builder. The last two params are optional.
builder = SphinxMultiBuilder(["./doc", "./build/api/doc"], # input directories
"/tmp", # Temp directory where symlinks are placed.
"./build/sphinx" # Output directory
["-m", "html", "-c", "./build/doc"], # Sphinx arguments this doesn't include the in- and output directory.
["index.rst"], # Specific files to build(optional).
handle_autobuild_error) # Handler that will be symlink en symlink error oc autobuild(optional).
# build once
builder.build()
# start autobuilding on change in any input directory. untill ctrl+c is pressed.
builder.start_autobuilding()
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
builder.stop_autobuilding()
builder.join_autobuilder()
# return the last exit code sphinx build returned had as program exit code.
sys.exit(builder.get_last_exit_code())
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.