1# libCEED: Documentation 2 3This page provides a brief description of the documentation for the libCEED library. 4 5## Quick build 6 7If you have Python and Doxygen installed, these two commands should build the documentation in `doc/sphinx/build/html/`. 8 9```sh 10pip install --user -r doc/sphinx/requirements.txt # only needed once 11make doc # builds HTML site 12``` 13 14## Sphinx 15 16Sphinx 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 18To 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 20The Sphinx API documentation depends on Doxygen's XML output (via the `breathe` plugin). Build these files in the `xml/` directory via: 21 22```sh 23make doxygen 24``` 25 26If you are editing documentation, such as the reStructuredText files in `doc/sphinx/source`, you can rebuild incrementally via 27 28```sh 29make -C doc/sphinx html 30``` 31 32which will HTML docs in the [doc/sphinx/build](./sphinx/build) directory. Use 33 34```sh 35make -C doc/sphinx latexpdf 36``` 37 38to build PDF using the LaTeX toolchain (which must be installed). 39This requires the `rsvg-convert` utility, which is likely available from your package manager under `librsvg` or `librsvg2-bin`. 40 41For more Sphinx features, see 42 43```sh 44make -C doc/sphinx help 45``` 46 47### Dependencies 48 49Some 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 51```sh 52pip install --user -r doc/sphinx/requirements.txt 53``` 54 55from toplevel. 56You can use `virtualenv` to keep these extensions isolated, and to check that all necessary extensions are included. 57 58```sh 59virtualenv VENV # create a virtual environment 60. VENV/bin/active # activate the environment 61pip install -r doc/sphinx/requirements.txt # install dependencies inside VENV 62make doc 63``` 64