1*4c4400c7SValeria Barra# libCEED: Documentation 2*4c4400c7SValeria Barra 3*4c4400c7SValeria BarraThis page provides a brief description of the documentation for the libCEED library. 4*4c4400c7SValeria Barra 5*4c4400c7SValeria Barra## Quick build 6*4c4400c7SValeria Barra 7*4c4400c7SValeria BarraIf you have Python and Doxygen installed, these two commands should build the documentation in `doc/sphinx/build/html/`. 8*4c4400c7SValeria Barra 9*4c4400c7SValeria Barra```sh 10*4c4400c7SValeria Barrapip install --user -r doc/sphinx/requirements.txt # only needed once 11*4c4400c7SValeria Barramake doc # builds HTML site 12*4c4400c7SValeria Barra``` 13*4c4400c7SValeria Barra 14*4c4400c7SValeria Barra## Sphinx 15*4c4400c7SValeria Barra 16*4c4400c7SValeria BarraSphinx is the tool used for libCEED's User Manual. Sphinx can produce documentation in different output formats: HTML, LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, and plain text. Sphinx comes with a broad set of extensions for different features, for instance the automatic inclusion of documentation from docstrings and snippets of codes, support of todo items, highlighting of code, and math rendering. 17*4c4400c7SValeria Barra 18*4c4400c7SValeria BarraTo be able to contribute to libCEED's User Manual, Sphinx needs to be [installed](http://www.sphinx-doc.org/en/master/usage/installation.html) together with its desired extensions. 19*4c4400c7SValeria Barra 20*4c4400c7SValeria BarraThe Sphinx API documentation depends on Doxygen's XML output (via the `breathe` plugin). Build these files in the `xml/` directory via: 21*4c4400c7SValeria Barra 22*4c4400c7SValeria Barra```sh 23*4c4400c7SValeria Barramake doxygen 24*4c4400c7SValeria Barra``` 25*4c4400c7SValeria Barra 26*4c4400c7SValeria BarraIf you are editing documentation, such as the reStructuredText files in `doc/sphinx/source`, you can rebuild incrementally via 27*4c4400c7SValeria Barra 28*4c4400c7SValeria Barra```sh 29*4c4400c7SValeria Barramake -C doc/sphinx html 30*4c4400c7SValeria Barra``` 31*4c4400c7SValeria Barra 32*4c4400c7SValeria Barrawhich will HTML docs in the [doc/sphinx/build](./sphinx/build) directory. Use 33*4c4400c7SValeria Barra 34*4c4400c7SValeria Barra```sh 35*4c4400c7SValeria Barramake -C doc/sphinx latexpdf 36*4c4400c7SValeria Barra``` 37*4c4400c7SValeria Barra 38*4c4400c7SValeria Barrato build PDF using the LaTeX toolchain (which must be installed). 39*4c4400c7SValeria BarraThis requires the `rsvg-convert` utility, which is likely available from your package manager under `librsvg` or `librsvg2-bin`. 40*4c4400c7SValeria Barra 41*4c4400c7SValeria BarraFor more Sphinx features, see 42*4c4400c7SValeria Barra 43*4c4400c7SValeria Barra```sh 44*4c4400c7SValeria Barramake -C doc/sphinx help 45*4c4400c7SValeria Barra``` 46*4c4400c7SValeria Barra 47*4c4400c7SValeria Barra### Dependencies 48*4c4400c7SValeria Barra 49*4c4400c7SValeria BarraSome of the extensions used require installation. They are distributed on [PyPI](https://pypi.org) and can be installed with `pip`. The extensions used for this project can be found in the [requiremenets file](./sphinx/requirements.txt) and can be readily installed by running: 50*4c4400c7SValeria Barra 51*4c4400c7SValeria Barra```sh 52*4c4400c7SValeria Barrapip install --user -r doc/sphinx/requirements.txt 53*4c4400c7SValeria Barra``` 54*4c4400c7SValeria Barra 55*4c4400c7SValeria Barrafrom toplevel. 56*4c4400c7SValeria BarraYou can use `virtualenv` to keep these extensions isolated, and to check that all necessary extensions are included. 57*4c4400c7SValeria Barra 58*4c4400c7SValeria Barra```sh 59*4c4400c7SValeria Barravirtualenv VENV # create a virtual environment 60*4c4400c7SValeria Barra. VENV/bin/active # activate the environment 61*4c4400c7SValeria Barrapip install -r doc/sphinx/requirements.txt # install dependencies inside VENV 62*4c4400c7SValeria Barramake doc 63*4c4400c7SValeria Barra``` 64