Metadata-Version: 1.1
Name: sphinx-multibuild
Version: 1.2.1
Summary: Allow sphinx to build with multiple source directories and watch for changes.
Home-page: https://github.com/rowanG077/sphinx-multibuild
Author: Rowan Goemans
Author-email: goemansrowan@gmail.com
License: MIT
Download-URL: https://github.com/rowanG077/sphinx-multibuild/archive/1.2.1.tar.gz
Description: sphinx-multibuild
        =================
        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.
        
        .. warning::
            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 <https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/>`_.
        
        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:
        
        
        .. code-block:: python
        
            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())
        
Keywords: sphinx,autobuild,multiple-directories
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
