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 zc.buildout, you
can use the package directly as a
recipe and configure the
documentation builder within your buildout configuration file.
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
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.
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.
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
--source=<URLS>: 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, Git is assumed:
--grouping=<GROUP>: 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.
docbuilderscript will check out the packages and run the documentation build process in this folder. This parameter is mandatory as well.
--output-directory=<PATH>: This is where the folder tree for the HTML output is stored, which links back into the build tree defined by the
working-directoryparameter. If it is not specified, the HTML output tree will end up in a folder named html inside the
--trunk-only: This flag is unset by default. If you set this flag only documentation from the main development branch will be built.
--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.
--verbose: Set the log verbosity. If
--vis specified you will see more detailed logging output. If you specify it more than once all
Sphinxdocumentation build output will be shown as well.
--index-template=<PATH>: This optional parameter contains a filesystem path to a folder containing a Sphinx configuration (a
conf.pyfile) and templates/static files. If you provide such a path
dataflake.docbuilderwill use it to build additional content for the
output-directoryfolder and auto-generate an index file. Please note: This folder must not contain an
index.rstdocument, as the index file will be auto-generated during the documentation build process. You can optionally provide a template named
index-templatefolder, which will have the autogenerated package list appended at the end.
--index-name=<NAME>: The file name, sans extension, for the index file. A ReST source file
<NAME>.rstwill be created containing links to the documented packages, and Sphinx will compile it to the final
<NAME>.htmloutput. The default value is
--docs-directory=<NAME>: 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.
--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
or by adding them to your zc.buildout configuration.
In a zc.buildout configuration file, the
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
which builds the Sphinx documentation found in the
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
--sourceparameters shown above. Mandatory.
groupings: One or more
--groupingparameters as shown above.
--working-directoryparameter shown above. If none is specified, a default of
--output-directoryparameter shown above
--trunk-onlyparameter shown above
--max-tagsparameter shown above
--verboseparameter shown above
index-templateparameter shown above
--index-nameparameter shown above
--docs-directoryparameter shown above