Merge "Add PDF doc generation for project docs goal for Train"
This commit is contained in:
commit
2c2b3cc4b1
|
@ -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 <https://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-rst-guides.html>`_.
|
||||
|
||||
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 <https://review.openstack.org/#/c/509297/>`_
|
||||
in October of 2017.
|
||||
|
||||
Discussion did happen on the `mailing list <http://lists.openstack.org/pipermail/openstack-dev/2017-October/123076.html>`_
|
||||
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.
|
Loading…
Reference in New Issue