doc: add requirements.txt and update doc-building instructions

228f70c5 · Dimitris Lampridis · 87e2e570 · 228f70c5 · 228f70c5 · 228f70c5
Commit 228f70c5 authored May 09, 2019 by Dimitris Lampridis
Hide whitespace changes
Inline Side-by-side

Showing with 56 additions and 29 deletions

.gitignore doc/.gitignore +1 -0

README doc/README +50 -29

requirements.txt doc/requirements.txt +5 -0

No files found.
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -2,3 +2,4 @@ _*
 doxygen-trtl-output/
 registers/wbgen/
 .doxystamp
+build_env
--- a/doc/README
+++ b/doc/README
-This documentation is based on sphinx. Here a random list of known
-dependencies:
- doxygen (to extract a database of symbols from the C libraries)
- GraphViz (to include images)
- ImageMagick (to include images)
- Python (to run sphinx)
-  - docutils
-  - sphinx
-  - sphinx_rtd_theme
-
-If you want to generate HTML (suggested), probably the list above it enough.
-
-    make -C doc html
-
-In order to generate the PDF version you need texlive and some extrapackages.
-This really depends on your distribution and how latex packages are packed.
-For this reason we suggest you to download the PDF provided by the Mock Turtle
-team on the official web site, or to adjust your texlive installation according
-to needs.
-
-   make -C doc latexpdf
-
-Here good tips about how to install sphinx:
-
-https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
-
-
-HTML and PDF are supported and tested, any other format is not directly
-supported.
\ No newline at end of file
+Documentation Build Instructions
+================================
+
+This project uses [Sphinx](http://www.sphinx-doc.org/en/master/) to generate documentation from
+[reStructuredText](http://docutils.sourceforge.net/rst.html) and
+[CommonMark](https://commonmark.org/) (Markdown) files under `doc/`.
+
+To build the documentation, it is highly recommended to setup a [Python virtual
+environment](https://virtualenv.pypa.io/en/stable/) where the necessary packages (docuilts, sphinx,
+etc.) can be installed via [pip](https://pypi.org/project/pip/) and be kept at a specific version.
+
+The following steps illustrate how to do this on a Debian/Ubuntu Linux box, with the virtual
+environment placed inside the `doc/` folder of the project itself:
+
+```
+$> sudo apt install virtualenv
+$> cd doc
+$> virtualenv build_env
+$> . build_env/bin/activate
+$> pip install -r requirements.txt
+$> deactivate
+```
+
+**Note:** If you use the same folder name and location (`doc/build_env`) for the virtual environment as
+in the above example, there is already a gitignore rule in place that will not track any
+auto-generated files within that folder.
+
+Once the environment is installed, you can (re)build the documentation by doing:
+
+```
+$> cd doc
+$> . build_env/bin/activate
+$> make html
+$> deactivate
+```
+
+The generated documentation can be accessed by opening `doc/_build/html/index.html` in your browser.
+
+Alternatively, if you have [LaTeX](https://www.latex-project.org/) installed, you can produce a PDF
+by doing:
+
+```
+$> cd doc
+$> . build_env/bin/activate
+$> make latexpdf
+$> deactivate
+```
+The generated documentation can be accessed by opening the PDF found under `doc/_build/latex/`.
+
+**Note:** Only HTML and PDF outputs from Sphinx are supported and tested.
\ No newline at end of file
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
+docutils==0.14
+Sphinx==1.8.3
+sphinx_rtd_theme
+breathe==4.10.0
+recommonmark==0.5.0