dataflake.docbuilder 1.12

Automated Sphinx documentation builder

This package provides a set of scripts to automate building Sphinx-based package documentation for packages hosted on a Subversion revision control server. They will…

• check out the current development trunk and all tagged versions

• build all Sphinx-based documentation in them, if it exists

• stitch together the trunk and release versions in a single HTML file to provide a simple jump-off page for all package versions

• rebuild the Sphinx documentation if there were any changes since the last build

Documentation

Full documentation for the last released version is at http://packages.python.org/dataflake.docbuilder. For documentation matching the current SVN trunk please visit http://docs.dataflake.org/dataflake.docbuilder.

Bug tracker

A bug tracker is available at https://bugs.launchpad.net/dataflake.docbuilder

SVN version

You can retrieve the latest code from Subversion using setuptools or zc.buildout via this URL:

http://svn.dataflake.org/svn/dataflake.docbuilder/trunk#egg=dataflake.docbuilder

---

Change log

1.12 (2011-08-30)

• Be more resilient when simple ReST text compilation or Sphinx building fails. Now the whole documentation build process won’t just fail at that point.

• provide more meaningful log messages when running with the -v option.

1.11 (2011-08-09)

• Now you can use Git alongside Mercurial and Subversion to use as version control system.

1.10 (2011-08-09)

• Taking more control of logging by defining our own logger and suppressing standard Sphinx log output. The new script flag -v or --verbose enables the user to determine what to show. Without it, only serious warnings are shown. With -v specified once you will see script progress output and notes about Sphinx build warnings. With -vv all Sphinx output is shown as well.

1.9 (2011-08-09)

• Now using pkg_resources.parse_version to parse the tag names and produce correct release ordering for each package

• Instead of using a flag to set the revision control system across all packages you now specify the revision control system per package with a simple prefix:

  [hg]http://myserver/hg/mypackage
  [svn]https://myservr/svnmypackage

  For backwards compatibility, all URLs without prefix are assumed to point to a Subversion repository.

1.8 (2011-08-05)

• Feature: You can now use either Subversion or Mercurial to check out documented packages.

1.7 (2010-08-03)

• Feature: If no standard package documentation can be found, the setuptools long_description settings is used as a last fallback to at least generate a single page for a package.

• Feature: To style the long_description fallback ReST documentation, a new parameter fallback-css can be used to provide a path to a CSS file.

1.6 (2010-07-31)

• Bug: If the z3csphinx-output-directory was set, all its contained packages ended up on the index document. Now this only happens if no SVN source URLs are otherwise provided. If they are, only packages from those source URLs are considered for linking on the index document.

1.5 (2010-07-31)

• Feature: If you generate some documentation via z3c.recipe.sphinxdoc and want to stitch links to it into the generated index file, you can use the new z3csphinx-output-directory parameter to point the script to the generated package documentation root folder.

1.4 (2010-07-31)

• Bug: Don’t clean up intermediate files, otherwise it is not possible to re-use a template folder for creating several separate pages into an output folder.

• Bug: Clean up group header creation to avoid header level mixups.

• Bug: When creating a missing required index.rst, use a template file if it exists.

1.3 (2010-07-30)

• Feature: Added a script and buildout option index-name to specify the file name (without extension) for the index page. With this option you can safely build the index page into an existing Sphinx documentation folder without overwriting or changing the existing index.rst file and its HTML equivalent. The default continues to be index.rst, though.

• Feature removed: It is no longer possible to create a simple HTML index page without using Sphinx and a minimal Sphinx configuration.

1.2 (2010-07-29)

• Feature: Add new script option -g/--grouping and zc.buildout option grouping to group packages.

• Miscellaneous: Renamed the zc.buildout option source to sources since it contains one or more elements.

• Miscellaneous: Removed the version pinning on the Sphinx dependency since our other dependency (repoze.sphinx.autointerface) is now compatible with Sphinx 1.0.

• Bug: If pkg_resources.find_distributions cannot find valid Egg distributions we still force the tag folder itself into the pkg_resources.working_set as a fallback.

1.1 (2010-07-25)

• Feature: The user can now provide a Sphinx configuration folder path that will be used to generate additional content for the documentation root folder.

• Factoring: Moved the DocsBuilder class into its own module.

• Factoring: Save run state on the documentation builder class instead of handing it around

• Cosmetic: Use a flat hierarchy when creating the HTML output links instead of a folder per package. Only a single index page needs to be created that way.

1.0 (2010-07-23)

• Initial release

---

Download