There have been a couple of threads about an updated "PTI" for documentation bouncing around the mailing list of late.
* http://lists.openstack.org/pipermail/openstack-dev/2018-March/128817 .html * http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594 .html 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 change. * 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 burden. * 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 setup.py 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 extensions. 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 setup.py 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 setup.py 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. Cheers, Stephen PS: For those that curious, the decision on whether to run 'python setup.py 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'. [1] https://docs.openstack.org/openstackdocstheme/latest/#using-the-theme [2] https://pypi.org/project/sphinxcontrib-apidoc/ [3] https://pypi.org/project/sphinxcontrib-apidoc/#migration-from-pbr __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
