Removal of DocBook XML Support¶
https://blueprints.launchpad.net/openstack-manuals/+spec/docbook-removal
With the last conversions to RST done for the Newton cycle, we can simplify our tools to only handle RST and thus remove DocBook XML support.
Problem description¶
The tools support DocBook XML which is not needed for Newton deliverables.
Right now the tools are used to build and publish DocBook XML for:
- The
troverepository. - The
api-siterepository. - The
openstack-manualsrepository on kilo and liberty stable branches. - The
operations-guiderepository.
The operations-guide repository has one guide that is nearly finished with RST conversion. The api-site repository contains the API reference which is currently converted to RST. The trove repository work has not started.
Additionally, the clouddocs-maven-plugin is used to publish
DocBook XML manuals. It is used also in heat, senlin, and zaqar
repositories for documents that are not published at all.
Proposed change¶
Simplify all tools to only handle RST, remove support for DocBook XML.
Freeze the clouddocs-maven-plugin, we will not do any new features for it and retire the repository as soon as projects are not using it anymore for publishing of documents.
Alternatives¶
- Keep status quo.
Implementation¶
Assignee(s)¶
- Primary assignee:
- jaegerandi (Andreas Jaeger)
Work Items¶
- Discuss with trove team the removal.
- Inform heat, senlin, zaqar teams about removal.
- For repositories that need XML publishing: Pin the openstack-doc-tools version to 0.34 since that is the last release with XML support.
- Convert glossary to RST and remove XML publishing from openstack-manuals repository.
- Remove DocBook XML publishing from openstack-doc-tools.
- Remove DocBook translation handling from openstack-doc-tools.
- Update contributor guide for this change.
- Update documentation in openstack-doc-tools for this change.
Dependencies¶
- Publishing of RST version of OPS guide.
Testing¶
- Testing of the tools will be done manually and as part of the builds. We should add some method to do integration testing.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.