Removal of DocBook XML Support

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.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

docs-specs