PySCF website and documentation

Overview

The PySCF website and documentation are written in a combination of Markdown and reStructuredText, using sphinx-doc and several associated extensions to generate static html files that are served from the gh-pages branch. Pushes to this repository trigger a Github Action that builds and serves the updated website.

Building the docs locally

Requirements

Pip install the following packages, which are also listed in requirements.txt:

• pyscf
• sphinx
• sphinxcontrib-bibtex
• nbsphinx
• pydata-sphinx-theme
• myst-parser
• sphinx_design

If you have multiple versions of PySCF on your machine and you would like so use a specific version, set PYTHONPATH to include the specific PySCF source directory you want; otherwise, uncomment sys.path.append(os.path.abspath('path_to_pyscf')) in source/conf.py.

Building

All sphinx related sources files (i.e. .rst and .md) are contained in source and all webpage files (once they're generated) live in the build.

To generate the website (without the API docs) run the following from the main project directory. If you are running on Linux, and you want to build faster you can use make html_parallel.

make html

To generate the complete website (including the API docs) run the following from the main project directory. Since the API docs are large, this build is noticeably slower than just generating the website with make html. :warning: PySCF must be accessible in your current Python environment when you run make api_docs or make html_full.

make html_full

To see more of the options you can use with make, just use make help.

Serving

Finally to serve the website, you can run:

 python -m http.server --directory build/html

Viewing a forked repo GitHub Pages

The PySCF website is currently built and deployed to GitHub Pages any time a push is made to the master branch of the repository. The website is served out of the docs/ directory of the gh-pages branch. This is all controlled by a GitHub Action in .github/workflows/docs_deploy.yaml. If you forked this repository and you want to view the website on your own GitHub Pages, make sure to enable Actions on your repository, because they are disabled in forks by default.

How to contribute

Website pages can be written in Markdown .md or reStructuredTest .rst.

1. Add a rst (or md) file "your_method.rst" in the source/user directory in which one describes the basic theory and usage of the method. Reference "user/your_method.rst" in the "toctree" section in source/user.rst.
2. Add a rst (or md) file "your_module.rst" in the source/modules directory in which one lists the examples and the member classes and functions of the module (the API doc is then generated by autodoc). (In the "__init__.py" file of each module, one should include a simple usage section. See pyscf.dft.__init__.py as an example.) Reference "your_module.rst" in the "toctree" section in source/modules.rst.
3. Optionally, one could also add a rst file "your_method_develop.rst" in the source/contributor directory where one provides more detailed descriptions of the implementation and advanced guidelines for using and further development of the module.