Allow sphinx to build with multiple source directories and watch for changes.
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 with Python >= 2.7 on Linux and Windows Vista or later.
Since symlinks on Windows require admin privilege this script has to run in admin mode. It works without admin privilege on Windows 10 creators update if you have enabled developer mode.
How to install
You can use pip install to install the package: pip install sphinx-multibuild
Sphinx-autobuild respects the SHPINXBUILD environment variable and will use the contents of that to build. If it is not set it defaults to the python executable with -msphinx as the argument.
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 arguments are used by 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. Please note that no real files or directories may be placed in the temporary directory.
Here is an example of building a document with 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 continuously 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 sphinx-autobuild as a module and control the building programmatically. There is a single class SphinxMultiBuilder that you can instantiate and create builds or automatically build on change:
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(# input directories ["./doc", "./build/api/doc"], # Temp directory where symlinks are placed. "/tmp", # Output directory "./build/sphinx" # Sphinx arguments, this doesn't include the in- # and output directory and filenames argments. ["-m", "html", "-c", "./build/doc"], # Specific files to build(optional). ["index.rst"], # Callback that will be called when symlinking # error occurs during autobuilding. (optional) handle_autobuild_error) # build once builder.build() # start autobuilding on change in any input directory until ctrl+c is pressed. builder.start_autobuilding() try: while True: time.sleep(1) except KeyboardInterrupt: builder.stop_autobuilding() # return the last exit code sphinx build returned had as program exit code. sys.exit(builder.get_last_exit_code())
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.