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 Subversion, Mercurial or
    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 <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, :term:`Git` is assumed::
  
    [hg]https://myserver/hg/mypackage
    [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 :mod:`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 :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=<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 :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/<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
