OpenStack Doc Tools Release Notes

3.0.0

Upgrade Notes

  • Python 2.7 support has been dropped. Last release of openstack-doc-tools to support python 2.7 is 2.0.0. The minimum version of Python now supported by openstack-doc-tools is Python 3.6.

2.0.0

Upgrade Notes

  • The helpers openstack-indexpage and openstack-jsoncheck are not used anymore and thus have been removed.

Critical Issues

  • Change publishing from publish-docs to publish-docs/html. This needs changing in build and publish CI jobs.

1.7.0

Upgrade Notes

  • The autogenerate_config_docs set of tools has been removed. These were always buggy and hard to maintain, and they have been superseded by the oslo_config.sphinxext Sphinx extension.

  • The openstack-auto-commands command and its helper script in bin/doc-tools-update-cli-reference have been removed. These have been superseded by the cliff.sphinxext Sphinx extensions.

  • The following scripts and tools have been removed:

    • prettify.py$

    • remove_trailing_whitespaces.sh$

    • remove_unnecessary_spaces.py$

    • retf$

    These were all indented to cleanup docs once they were already in tree, but our tooling and review process should be sufficient to catch most issues and there’s limited value in submitting whitespace-fixup patches.

1.6.0

New Features

Upgrade Notes

  • The extract_swift_flags tool no longer supports the docbook command. This previously allowed outputting of Docbook-formatted text but the feature was broken and unsupported by the community. reStructuredText should be used for everything.

  • The extract_swift_flags tool no longer supports the –from argument. All Swift documentation has been converted to reStructuredText meaning there is no reason to keep this around.

  • The extract_swift_flags.py script has been removed, and the autohelp.py and diff_branches.py scripts no longer build config file documentation for the swift project. The swift dev team had been manually maintaining their config files in-tree and to avoid duplication, doc and swift have agreed to link the config ref out to the dev docs. As such, there is therefore no reason to keep this tooling around.

1.4.0

Bug Fixes

  • Fix building of translations on older branches where the DebConf Install Guide does not exist.

1.2.1

Bug Fixes

  • Fix doc-tools-check-languages, it used a wrong way of passing arguments to tox and failed therefore with tox 2.5.0.

Other Notes

  • The configuration items for autohelp are now in the openstack-manuals repository.

  • Use jinja templating system to generate configuration reference tables.

  • Unsupport OpenStackClient in CLI Reference in favor of docs in the OSC project itself.

  • autohelp.py update will create the flagmappings file if it doesn’t exist yet.

1.1.0

Other Notes

1.0.0

Prelude

The most important change in this release is the removal of DocBook XML support. Support for checking, building, and translation of DocBook XML files has been removed. The tools now only handle RST files.

0.33.0

New Features

  • Update CLI Reference generation tool for RST. To migrate CLI Reference from DocBook to RST, output the documentation in RST format, with a few work arounds for RST/Sphinx specific issues.

  • Set the bug report project to openstack-i18n for the translated documents.

  • New command openstack-indexpage to only generate the HTML index page. The index page layout has also been improved.

Other Notes

  • autohelp.py now allows overrides of sections, defined in <project>.overrides configuration files.

0.32.0

New Features

  • The autohelp tools export now also RST tables.

Bug Fixes

  • Rework install guide translation build tool to process toctree for each distribution dynamically.

Other Notes

  • Use reno for release note management.

  • extract_swift_flags.py now reads the options help strings from RST tables.

  • The outdated virtual build and test environment has been removed.