Writing Forte’s documentation

Location and structure of Forte’s documentation

Forte uses sphinx to generate its documentation. The documentation is written in part in sphinx, with some of the content generated from Jupyter notebooks. The documentation is contained in the directory docs, which has the following structure:

docs
├── notebooks
└── source

source contains the restructured text files (rst) that are compiled by sphinx. The directory notebooks contains Jupyter notebooks that are used to generate some of the rst files. Restructured text file prefixed with nb_ that live in source are generated from jupyter notebooks contained in the notebooks directory.

Note that the location of these converted jupyter notebooks reflects the relative location in the notebooks directory. For example, the file docs/source/nb_00_overview.rst is generated from the file docs/notebooks/nb_00_overview.ipynb.

Compiling the documentation

To compile the documentation on your local machine, from a terminal change to the docs folder and type

docs> make html

This command will run sphinx and generate the documentation in the folder docs/build/html. The documentation main page can be accessed via web browser using the url docs/build/html/index.html

Contributing to the documentation

To modify a section of Forte’s documentation you should first identify which file to modify. If a rst file begins with nb_, then you should edit the corresponding jupyter notebook located in docs/notebooks or one of its subdirectories.

If you modified notebook files, you can update the corresponding rst files using the update_rst.py script in the docs directory:

docs> python update_rst.py

Since Jupyter facilitates the editing and rendering of the documentation, it is recommended to do all edits of Jupyter documents in Jupyter, and only at the end (for example, before a commit) to convert the content to rst files.