Building Documentations

Documentations are based on Sphinx. Here we explain steps to build documentations from source, that is, to generate the documentation web pages.

There are two packages: pomdp_py and pomdp_py.problems. Their documentations are built separately.

Building docs for pomdp_py

1. Go to the sphinx source directory:

   cd pomdp-py/docs/_sphinx_src
   

2. Building docs for pomdp_py. Run sphinx-apidoc:

   sphinx-apidoc -o api/ ../../pomdp_py
   

   This generates .rst files for different modules in the pomdp_py package.

   The first argument api specifies the output directory for these .rst files to be api.

   The second argument ../../pomdp_py specifies the path to the pomdp_py package (Note that this should be the package’s root path that contains __init__.py).

   Refer to sphinx-apidoc for more information.

3. Generate web pages:

   make html
   

   This outputs to pomdp-py/docs/html

Building docs for pomdp_py.problems

1. Go to the sphinx source directory:

   cd pomdp-py/docs/_sphinx_src
   

2. Building docs for pomdp_py. Run sphinx-apidoc:

   sphinx-apidoc -o problems/ ../../pomdp_py/problems
   

3. Generate web pages:

   make html
   

   This outputs to pomdp-py/docs/html

Note that when creating the documentation for a problem under pomdp_py.problems, you may want to re-use the README file on github for the documentation. To do that, first create a read-me file at pomdp_py/problems/<problem>/README.rst with desirable content that describes the problem. Then, include this read-me file at the top of the generated pomdp_py.problems.<problem>.rst, like so:

.. include:: ../../../pomdp_py/problems/<problem>/README.rst

Note on Changelog

Changelog is generated based on CHANGELOG.rst in the repository’s root directory. When the website is constructed, the _sphinx_src/changelog.rst is a symbolic link to CHANGELOG.rst, created by

cd _sphinx_src
ln -s ../../CHANGELOG.rst changelog.rst

But because github pages cannot access ../../CHANGELOG.rst, this symbolic has to be removed when the site is deployed.