Enabling PDF generation support for project documentation

During the Ocata cycle, the OpenStack-manuals, infra, and translations team worked together to enable the generation of PDF doc files from rst-based guide documents. This change generated a single downloadable PDF per Sphinx project. This means that each “book” built from a single Sphinx project could generate a PDF, allowing users who want to see documents offline the ability to do so.

The work was completed at the end of the Ocata release, but was never implemented within the project repositories. This means that our users are only able to download PDF documents for the Installation Guide, the Contributor Guide, and the Image Guide, limiting the scope for our offline users.

This goal proposes we enable support across the project repositories to further our goal of being an accessible open source community.

Note

With regards to ensuring the information is up-to-date, doc patches will continue to be implemented as per usual in the project repositories. It is important to note that the generation of these guides is to be the responsibility of the user to ensure the content they are reading is relevant to their deployment.

Champion

Alexandra Settle (asettle) - SUSE

Gerrit Topic

To facilitate tracking, commits related to this goal should use the gerrit topic:

pdf-doc-enabled

Completion Criteria

The completion criteria for this goal is as follows:

  1. Each team needs to ensure they can build PDFs and that the PDFs look respectable and readable. This definition is dependent per-project and should be explored at the discretion of the project team.

  2. Each team needs to define a new tox env to enable the PDF build.

  3. It is possible to run Sphinx using the configuration in doc/source and generate a single PDF file containing all of the documentation in that directory.

    Note

    Publishing multiple PDFs not part of this goal, and should be deferred until after this goal is complete.

  4. Each guide generated includes the release version to ensure the user is fully aware of the content they have built. It would also be helpful to add a disclaimer that this information is updated regularly in the project repositories and to check for updates during maintenance periods.

References

The OpenStack-manuals project has already enabled support for PDF generation. The specification is viewable here.

This work was proposed earlier, but never went further than a draft specification for docs-specs. Ian Choi proposed PDFs for project-specific docs with unified doc builds in October of 2017.

Discussion did happen on the mailing list but did not go much further, but there has been interest for some time.

Current State / Anticipated Impact

The above resources provide an overview of the work that was started, but never completed. At this point in time, I see this as a necessary final task to ensure our documentation is as accessible as it can be for all users.