1 files changed, 100 insertions, 0 deletions
diff --git a/doc/HowToBuildTheDocs.txt b/doc/HowToBuildTheDocs.txt
new file mode 100644
index 00000000..26c89d23
--- /dev/null
+++ b/doc/HowToBuildTheDocs.txt
@@ -0,0 +1,100 @@
+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 rst2pdf (https://pypi.org/project/rst2pdf/) installed:
+
+	pip install rst2pdf
+
+	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
+--------------------------
+
+From the `doc` location run:
+
+
+sphinx-build -b pdf src .
+
+
+This will then generate a single PDF for all of the documentation within `doc`.
+
+
+
+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.htm reflects the latest release and had 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)