diff --git a/docs/source/devguide/docbuild.rst b/docs/source/devguide/docbuild.rst new file mode 100644 index 000000000..5d7ef8ac7 --- /dev/null +++ b/docs/source/devguide/docbuild.rst @@ -0,0 +1,64 @@ +.. _devguide_docbuild: + +============================= +Building Sphinx Documentation +============================= + +In order to build the documentation in the ``docs`` directory, you will need to +have the Sphinx_ third-party Python package. The easiest way to install Sphinx +is via pip: + +.. code-block:: sh + + sudo pip install sphinx + +Additionally, you will also need two Sphinx extensions for TikZ support and +numbering figures. The sphinxcontrib-tikz_ package should be installed directly +from the git repository as such: + +.. code-block:: sh + + git clone https://bitbucket.org/philexander/tikz.git + cd tikz + sudo python setup.py install + +The Numfig_ package can be installed directly with pip: + +.. code-block:: sh + + sudo pip install sphinx-numfig + +----------------------------------- +Building Documentation as a Webpage +----------------------------------- + +To build the documentation as a webpage (what appears at +http://mit-crpg.github.io/openmc), simply go to the ``docs`` directory and run: + +.. code-block:: sh + + make html + +------------------------------- +Building Documentation as a PDF +------------------------------- + +To build PDF documentation, you will need to have a LaTeX distribution installed +on your computer as well as Inkscape_, which is used to convert .svg files to +.pdf files. Inkscape can be installed in a Debian-derivative with: + +.. code-block:: sh + + sudo apt-get install inkscape + +One the pre-requisites are installed, simply go to the ``docs`` directory and +run: + +.. code-block:: sh + + make latexpdf + +.. _Sphinx: http://sphinx-doc.org +.. _sphinxcontrib-tikz: https://bitbucket.org/philexander/tikz +.. _Numfig: https://pypi.python.org/pypi/sphinx_numfig +.. _Inkscape: https://inkscape.org diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 999de9a53..03838363c 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -18,3 +18,4 @@ as debugging. xml-parsing statepoint voxel + docbuild