2.5 KiB
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
trove
repository. - The
api-site
repository. - The
openstack-manuals
repository on kilo and liberty stable branches. - The
operations-guide
repository.
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.