Using dataflake.docbuilder

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.

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 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 <URLS> 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:

    [git]https://myserver/git/mypackage
https://github.com/organization/myotherpackage.git

  • -g <GROUP> or --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.

  • -w <PATH> or --working-directory=<PATH>: The docbuilder script will check out the packages and run the documentation build process in this folder. This parameter is mandatory as well.

  • -o <PATH> or --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-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 Sphinx documentation 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.py file) and templates/static files. If you provide such a path 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=<NAME>: The file name, sans extension, for the index file. A ReST source file <NAME>.rst will be created containing links to the documented packages, and Sphinx will compile it to the final <NAME>.html output. The default value is index.

  • --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.

  • -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 zc.buildout configuration.

From zc.buildout

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 docbuilderdocs 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 --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/<SCRIPTNAME> 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