Using dataflake.docbuilder ========================== :mod:`dataflake.docbuilder` can be used in two ways. It defines a `Setuptools` entry point called ``docbuilder``, which automatically creates a shell script ``docbuilder`` when the package is installed through `Setuptools`. If you are using :term:`zc.buildout`, you can use the package directly as a ``recipe`` and configure the documentation builder within your buildout configuration file. .. warning:: When the documentation build scripts build the `Sphinx` documentation, the downloaded packages are not fully installed. They only have their EGG-INFO structures created and are then added to ``sys.path`` for the time it takes to run the `Sphinx` builder so they can be imported. That means their dependencies are not installed automatically. If there are dependencies that must be available before the package can be imported or before the `Sphinx` documentation can be built (such as third-party `Sphinx` extensions) you must make them available yourself. How to do so is shown below. .. warning:: The document build script will call the Git script through the shell. Make sure you can check out or update the packages you want to document without receiving any prompts, e.g. for credentials, otherwise the script will just hang waiting for input on a prompt you will never see. From ``pip`` ------------ After installing :mod:`dataflake.docbuilder` using `Setuptools`, a shell script named ``docbuilder`` is created. This can be used to invoke the documentation build process and accepts several options, which you can discover yourself by running ``docbuilder -h`` or ``docbuilder --help``: * ``-s `` or ``--source=``: This `mandatory` parameter, which can be given multiple times, contains an URL to a package's location in a software version control repository. You can prefix the URL with information about the revision control server used, if no prefix is given, :term:`Git` is assumed:: [git]https://myserver/git/mypackage https://github.com/organization/myotherpackage.git * ``-g `` or ``--grouping=``: You can group packages into groups to set them apart in the HTML output. A GROUP element consists of the package name and the group name, separated by a colon (":") character. Example: `dataflake.docbuilder:dataflake`. * ``-w `` or ``--working-directory=``: The ``docbuilder`` script will check out the packages and run the documentation build process in this folder. This parameter is `mandatory` as well. * ``-o `` or ``--output-directory=``: This is where the folder tree for the HTML output is stored, which links back into the build tree defined by the ``working-directory`` parameter. If it is not specified, the HTML output tree will end up in a folder named `html` inside the ``working-directory``. * ``-t`` or ``--trunk-only``: This flag is unset by default. If you set this flag only documentation from the main development branch will be built. * ``-m`` or ``--max-tags``: When building documentation for the current development version and all tags this flag specifies how many tags to show on the main index page. If more tags exist, a link to a separate page is inserted that shows all tags for the given package. The default value is 5. * ``-v`` or ``--verbose``: Set the log verbosity. If ``--v`` is specified you will see more detailed logging output. If you specify it more than once all :mod:`Sphinx` documentation build output will be shown as well. * ``--index-template=``: This optional parameter contains a filesystem path to a folder containing a `Sphinx` configuration (a ``conf.py`` file) and templates/static files. If you provide such a path :mod:`dataflake.docbuilder` will use it to build additional content for the ``output-directory`` folder and auto-generate an index file. Please note: This folder must not contain an ``index.rst`` document, as the index file will be auto-generated during the documentation build process. You can optionally provide a template named ``index.rst.in`` in the ``index-template`` folder, which will have the autogenerated package list appended at the end. * ``--index-name=``: The file name, sans extension, for the index file. A ReST source file ``.rst`` will be created containing links to the documented packages, and `Sphinx` will compile it to the final ``.html`` output. The default value is ``index``. * ``--docs-directory=``: The folder name inside your software package checkout where `Sphinx` documentation is stored. By default, the folders `doc` and `docs` are searched. You can use this parameter multiple times to add other folder names to the default list. * ``-h`` or ``--help``: Show the help text. If the package to be documented or its `Sphinx` documentation configuration needs additional packages to be imported and run, you need to make them available yourself by e.g. using ``easy_install`` or by adding them to your :term:`zc.buildout` configuration. From :term:`zc.buildout` ------------------------ In a :term:`zc.buildout` configuration file, the :mod:`dataflake.docbuilder` package can be used directly as a recipe. The recipe will create a shell script that invokes the document build process with the options specified in the configuration stanza. Here's a simple example:: [buildout] parts = docbuilderdocs [docbuilderdocs] recipe = dataflake.docbuilder eggs = repoze.sphinx.autointerface sources = https://github.com/dataflake/dataflake.docbuilder.git This configuration will create a script named ``docbuilderdocs`` which builds the `Sphinx` documentation found in the :mod:`dataflake.docbuilder` development head and all tags. The following keywords can be used with this recipe (documentation see above): * ``eggs``: If the package to be documented or its `Sphinx` documentation configuration needs additional packages to be imported and run, you need to list them here so they get pulled in automatically. * ``sources``: Equivalent to one or more ``--source`` parameters shown above. Mandatory. * ``groupings``: One or more ``--grouping`` parameters as shown above. * ``working-directory``: The ``--working-directory`` parameter shown above. If none is specified, a default of ``{buildout:directory}/parts/`` is used. * ``output-directory``: The ``--output-directory`` parameter shown above * ``trunk-only``: The ``--trunk-only`` parameter shown above * ``max-tags``: The ``--max-tags`` parameter shown above * ``verbose``: The ``--verbose`` parameter shown above * ``index-template``: The ``index-template`` parameter shown above * ``index-name``: The ``--index-name`` parameter shown above * ``docs-directory``: The ``--docs-directory`` parameter shown above