OpenStack Doc Tools Release 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.
The helpers openstack-indexpage and openstack-jsoncheck are not used anymore and thus have been removed.
Change publishing from publish-docs to publish-docs/html. This needs changing in build and publish CI jobs.
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
openstack-auto-commandscommand and its helper script in
bin/doc-tools-update-cli-referencehave been removed. These have been superseded by the
The following scripts and tools have been removed:
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.
The documentation for this repo has been improved and is now published at https://docs.openstack.org/openstack-doc-tools/latest.
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.
Fix building of translations on older branches where the DebConf Install Guide does not exist.
Fix doc-tools-check-languages, it used a wrong way of passing arguments to tox and failed therefore with tox 2.5.0.
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.
For translated manuals, the command
doc-tools-check-languagesnow places a marker file in the root of each directory. This marker file is needed for proper publishing in the OpenStack CI environment. For details, see https://specs.openstack.org/openstack-infra/infra-specs/specs/doc-publishing.html.
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.
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.
openstack-indexpageto only generate the HTML index page. The index page layout has also been improved.
autohelp.pynow allows overrides of sections, defined in
The autohelp tools export now also RST tables.
Rework install guide translation build tool to process toctree for each distribution dynamically.
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.