Contributing to NWChemEx Documentation
In this section we explain the basic orgnization of the NWChemEx documentation system and present instructions on how to contribute to the documentation.
Structure of NWChemEx Documentation
In the repo of every NWChemEx package, there is a docs
directory. Under
this diretory there is a source
subdirectory which contains all .rst
source files of the documentation (recursive subdirectory structures may
exist). The files Makefile
and requirements.txt
are for generating
formatted files of the documentation, and will be explained below. The
README.md
file briefly decscribes the documentation and how to generate
the documentation files.
How to Contribute to NWChemEx Documentation
Suppose one plans to update the documentation of the package PluginPlay.
First, one should create a local working copy of the PluginPlay repo using
git clone
, then edit the existing .rst files or create new .rst files
under the doc
directory.
Remember, when new .rst files are added, one needs to add the names of the
new files into the toctree list in the index.rst
file under the same
directory.
When all editing work is done one needs to generate a local copy of the
documentation (see below), usually in html format, and check the .html files
in a browser to make sure everything is displayed properly. Finally one can
open a pull request to the PluginPlay repo and merge the updated documentation
to master.
Note: the developer documentation of NWChemEx resides in the .github repo.
How to Generate a Local Copy of the Documentation
NWChemEx uses Sphinx - a Python documentation generator to transform the
source files (.rst, .md. etc) into documentation files in various formats
(.html, .pdf, etc). One can see the content of the file requirements.txt
with the linux command vi
:
docutils<=0.19
sphinx
sphinx_rtd_theme
This list contains the required Python packages to install. We recommend to install these packags into a Python virtual environment, in order to avoid possible conflicts in the base environment. One can run the linux commands
python3 -m venv venv
. venv/bin/activate
pip3 install -r requirements.txt
to create a virtual environment venv
, activate it, and then install the
required packages into it.
Note: during the installation of the packages, one may see an error message
like “ERROR: sphinx-rtd-theme 1.2.0 has requirement docutils<0.19, but you’ll
have docutils 0.19 which is incompatible.”. This is a known issue, but not
affecting documentation generation.
After all packages are successfully installed, one can run
make html
under the directory of docs
to generate the documentation in .html format.
One can also choose other formats, for example, .pdf, for the generated
documentation files by running
make latexpdf
In this case the installation of additional packages such as latexmk
might
be necessary.
After successfully running these make
commands, a directory of build
would be created under docs
. So one can go to the subdirectories html
or latex
to check whether generated .html or .pdf files are correct or not.