Scribd
Upload
42 views3 pages

How To Build The Docs

This document provides instructions for building the Ghostscript documentation from Markdown files using Sphinx. It describes how to install Sphinx and its dependencies like LaTeX, the ReadTheDocs theme, and docutils Python package. It then explains how to edit documentation files, build HTML and PDF outputs, and update the documentation as needed.

Uploaded by

thiagomarianolance
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
42 views3 pages

How To Build The Docs

This document provides instructions for building the Ghostscript documentation from Markdown files using Sphinx. It describes how to install Sphinx and its dependencies like LaTeX, the ReadTheDocs theme, and docutils Python package. It then explains how to edit documentation files, build HTML and PDF outputs, and update the documentation as needed.

Uploaded by

thiagomarianolance
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
You are on page 1/ 3

How to build the Ghostscript documentation

==========================================

Welcome to the Ghostscript documentation. This documentation relies on Sphinx


(https://www.sphinx-doc.org/en/master/) to publish HTML & PDF docs from markdown
files written with restructured text / RST
(https://en.wikipedia.org/wiki/ReStructuredText).

Installing Sphinx & dependencies


--------------------------------

1. You should follow the instructions on the Sphinx website to install Sphinx on
your system.

2. Ensure you have Latex (https://www.latex-project.org/get/) installed

This ensures that you can build a PDF of the documentation.

3. The Sphinx documentation files also rely on the "readthedocs" theme to be


installed, follow the instructions here:
https://sphinx-rtd-theme.readthedocs.io/en/stable/installing.html

4. Once you have installed the "readthedocs" theme, depending on your OS, it will
also have installed a `docutils` (http://docutils.sourceforge.net/) Python package.

This should be okay, however if you have issues with building docs for PDF
ensure that the `docutils` version works for you.

To see what version you have do:

python3 -m pip show docutils

On Windows the required version was 0.18.1 to build PDF docs (pip install
docutils=0.18.1), however on other systems lower versions were fine.

Editing the documentation


-------------------------

Within this `src` folder update the associated `.rst` files which are in
restructured text format. These files represent the corresponding document pages.

Some notes on syntax


~~~~~~~~~~~~~~~~~~~~

- Use ``for inline code`` or ``computer/technical terminology``

- Use tab indented code for code blocks with, e.g. .. code-block:: bash

- For device names use :title:`deviceName` , e.g. :title:`pdfwrite`

- For headers underline text with ==== for h1 level, ---- for h2, ~~~~ for h3 &
"""" for h4
For full details on RST syntax, see:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/

Building HTML documentation


---------------------------

From the `doc` location run:

sphinx-build -b html src build

This then creates the HTML documentation within `doc/build` for your review, you
can then run `build/index.html` to check out the results.

Building PDF documentation


--------------------------

Ensure that `pdflatex` is on your PATH, test with:

pdflatex --help

Then create the latex build from the `doc` location:

sphinx-build -b latex src build/latex

Once done do:

cd build/latex
make

If there any warnings then hit return to pass through them to continue building
( also decide if you need to fix them or not ).

Now you should have Ghostscript.pdf ready within `build/latex`.

Move the Ghostscript.pdf file into the root of "doc" and replace the existing PDF
as required.

Updating the documentation


--------------------------

- Make your edits as required in the relevant RST files ( see above: Editing the
documentation )

- Test locally by building and running in local browser ( see above "Building HTML
documentation" )

- Ensure to update the version of Ghostscript cited in `conf.py` line 52 ( e.g.


release = "10.0.0" )

- Ensure that `News.html` reflects the latest release and has any further "news"
- Once changes are pushed to golden master then readthedocs.io should pick up the
changes, build & deploy the docs!

- Visit ghostscript.readthedocs.io once built and deployed to check

---

For more see: Using Sphinx (https://www.sphinx-doc.org/en/master/usage/index.html)

You might also like