| 1 |
Updating Documentation |
| 2 |
====================== |
| 3 |
|
| 4 |
Overview |
| 5 |
-------- |
| 6 |
|
| 7 |
This documentation is stored along with the source in the ``docs`` directory of the git tree and uses the `reStructuredText format <http://en.wikipedia.org/wiki/ReStructuredText>`_. |
| 8 |
|
| 9 |
We recommend reading this `reStructuredText Primer <http://sphinx-doc.org/rest.html>`_ before editing the docs for the first time. |
| 10 |
|
| 11 |
Compiling Docs |
| 12 |
-------------- |
| 13 |
|
| 14 |
The docs are compiled using `Sphinx Python Documentation Generator <http://sphinx-doc.org/>`_. The libMariaS3 build system already knows how to use this. To compile the docs please follow theses steps: |
| 15 |
|
| 16 |
#. Install the ``python-sphinx`` package using your distribution's package manager |
| 17 |
|
| 18 |
#. Re-run bootstrap as follows so that it picks up that Sphinx is installed:: |
| 19 |
|
| 20 |
./bootstrap.sh -m |
| 21 |
|
| 22 |
#. To compile in HTML format:: |
| 23 |
|
| 24 |
make html |
| 25 |
|
| 26 |
There will now be an HTML version of the docs in the ``/html`` directory of the source. |
| 27 |
|
| 28 |
Compiling PDF Docs |
| 29 |
------------------ |
| 30 |
|
| 31 |
Sphinx required LaTeX to build PDF docs. The following steps show you how to build PDF docs: |
| 32 |
|
| 33 |
#. Install ``python-sphinx`` as above |
| 34 |
|
| 35 |
#. Install the full *TeXLive* package. In Fedora this is ``texlive-scheme-full`` and ``texlive-full`` in Ubuntu |
| 36 |
|
| 37 |
#. Re-run bootstrap as follows so that it picks up that Sphinx and LaTeX are installed:: |
| 38 |
|
| 39 |
./bootstrap.sh -m |
| 40 |
|
| 41 |
#. To compile in PDF format:: |
| 42 |
|
| 43 |
make latexpdf |
| 44 |
|
| 45 |
The generated PDF will be in the ``/docs/latex/`` directory. |