From e1bb36be35257cd25d112ef5221fefc19d4a35f4 Mon Sep 17 00:00:00 2001 From: Alexandra Settle Date: Tue, 26 Mar 2019 11:08:09 +0000 Subject: [PATCH] Add PDF doc generation for project docs goal for Train This is designed to be a small, accessible goal for the community. My understanding is that we no longer require infra support to complete this goal, but I have added Monty Taylor to the review just in case. Change-Id: I1afda7ec016007de72fcbdb53aa9704fcba52f78 --- goals/train/pdf-doc-generation.rst | 79 ++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 goals/train/pdf-doc-generation.rst diff --git a/goals/train/pdf-doc-generation.rst b/goals/train/pdf-doc-generation.rst new file mode 100644 index 000000000..a4472ec05 --- /dev/null +++ b/goals/train/pdf-doc-generation.rst @@ -0,0 +1,79 @@ +========================================================= +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: + +#. 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. + +#. Each guide generated includes the release name 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.