There have been a couple of threads about an updated "PTI" for
documentation bouncing around the mailing list of late.


I've been told the reasoning behind this change and what is required
has not been made clear so here goes my attempt at explaining it. In
short, there are two problems we're trying to work around with this

 * The legacy 'build_sphinx' setuptools command provided by pbr has
   been found to be lacking. It's buggy as hell, frequently breaks with
   Sphinx version bumps, and is generally a PITA to maintain. We (the
   oslo team) want to remove this feature to ease our maintenance
 * The recent move to zuul v3 has changed how documentation is built in
   the gate. Previously, zuul called the 'docs' target in tox (e.g.
   'tox -e docs'), which would run whatever the project team had
   defined for that target. With zuul v3, zuul no longer calls this.
   Instead, it call either 'python build_sphinx' orĀ 'sphinx-
   build' (more on this below). This means everything you wish to do as
   part of the documentation build must now be done via Sphinx

Both the oslo and infra teams have a strong incentive to drop support
for the 'build_sphinx' command (albeit for different reasons) but doing
so isn't simply a case of calling 'sphinx-build' instead. In order to
migrate, some steps are required:

   1. pbr's 'build_sphinx' setuptools command provides some additional
      functionality on top of 'sphinx-build'. This must be replaced by
      Sphinx extensions.
   2. Calls to 'python build_sphinx' must be replaced by
      additional calls to 'sphinx-build'
   3. Documentation requirements must be moved to 'doc/requirements.txt'
      to avoid having to install every requirement of a project simply to
      build documentation.

The first of these has already be achieved: 'openstackdocstheme'
recently gained support for automatically configuring the project name
and version in generated documentation [1], which replaced that aspect
of the 'build_sphinx' command. Similarly, the 'sphinxcontrib-apidoc'
Sphinx extension [2] was produced in order to provide a way to
automatically generate API documentation as part of 'sphinx-build'
rather than by having to make a secondary call to 'sphinx-apidoc'
(which the gate, which, once again, no longer runs anything but
'sphinx-build' or 'python build_sphinx', would not do).

The second step is the troublesome bit and has been the reason for most
of the individual patches to various projects. The steps necessary to
make this change have been documented multiple times on the list but
they're listed here once again for posterity:

 * If necessary, enable 'sphinxcontrib.apidoc' as described at [3].
 * Make sure you're using 'openstackdocstheme', assuming your project
   is an official OpenStack one.
 * Remove the 'build_sphinx' section from 'setup.cfg' (this is
   described at [3] but applies whether you need that or not).
 * Update your doc/releasenotes/api-guide targets in 'tox.ini' so
   you're using the same commands as the gate.

The third change should be self-explanatory and infra have reasons for
requesting it. It's generally easiest to do this as part of the above.

Hopefully this clears things up for people. If anyone has any
questions, feel free to reach out to me on IRC (stephenfin) and I'll be
happy to help.


PS: For those that curious, the decision on whether to run 'python build_sphinx' command or 'sphinx-build' in the gate is based
on the presence of a 'build_sphinx' section in 'setup.cfg'. If present,
the former is run. If not, we use 'sphinx-build'. This is why it's
necessary to remove that section from 'setup.cfg'.


OpenStack Development Mailing List (not for usage questions)

Reply via email to