Skip to content

Latest commit

 

History

History
63 lines (39 loc) · 1.63 KB

README.rst

File metadata and controls

63 lines (39 loc) · 1.63 KB
Raw

Auto-documentation of the ixmp package

The documentation of the ix modeling platform is generated from .rst files in doc/source, and from numpy-format docstrings in the Python code.

Dependencies

  1. Sphinx v1.8 or higher
  2. sphinx_rtd_theme
  3. sphinxcontrib.bibtex
  4. numpydoc

These can be installed as 'extra' dependencies of the ixmp package. From the top-level directory of the repository, run:

pip install .[docs]

Writing in reStructuredText

There are a number of guides out there, e.g. on docutils.

Building the docs locally

Install the dependencies, above.

On Linux or Apple macOS, from the command line, run:

make html

On Windows, from the command line, run:

./make.bat

The build documentation is in doc/build/html/ and can be viewed by opening doc/build/html/index.html in a web browser.

Read the Docs

The official version of the documentation is hosted on Read The Docs (RTD) at https://message.iiasa.ac.at/projects/ixmp/. RTD builds the docs using a command similar to:

sphinx-build -T -E -d _build/doctrees-readthedocs -D language=en . \
  _build/html

This command is executed in the directory containing conf.py, i.e. doc/source/. Note that this is different from doc/, where the above make tools are invoked. Use this to test whether the documentation build works on RTD.