Sphinx-material theme for PySCF Docs (pyscf#57)

* First commit with material styling

* Changing the name of the files used in the main nav bar.

* Improving instructions

* Update site formatting and temporarily remove md support

* Adding docs dir so we can show the preview on GitHub pages

* Adding nojekyll file and updating instructions.

* Forgot to add the website files

* Forgot the API docs

* Think these missing source files were messing up the formatting for the whole site

* The nojekyll file got deleted

* Moving the instructions to README.md and fixing the rendering of tables.

* Fix typos and formatting

* Shiting to make for building website and updating the docs accordingly.

* Clean up and removing section numbers.

* Forgot to push doc files and source files

* Simplifying instructions in README.md

* Update LICENSE

* Removing html files

* Update README.md

Co-authored-by: Susi Lehtola <[email protected]>

* Fixing camel case in README.md and fixing small error in index.rst

Co-authored-by: Timothy Berkelbach <[email protected]>
Co-authored-by: Susi Lehtola <[email protected]>

.gitignore

@@ -102,3 +102,9 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# Extras
+.vscode
+.doctrees
+_website
+source/pyscf_api_docs

Makefile

@@ -19,11 +19,21 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html html_full api_docs gh_pages_setup html_parallel dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
+	@echo "Common Commands"
+	@echo "==============="
+	@echo "  html            to make standalone HTML files"
+	@echo "  api_docs        to make source files for the API docs section of the website"
+	@echo "  html_parallel   to make standalone HTML files in parallel (doesn't work for MacOS)"
+	@echo "  html_full       to make source files for API docs (AND) the standalone HTML files"
+	@echo "  gh_pages_setup  to make move the constructed website to the docs directory, where it will be rendered by GitHub pages after commit"
+	@echo ""
+	@echo ""
+	@echo "Less Common Commands"
+	@echo "===================="
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -51,10 +61,45 @@ clean:
 	rm -rf $(BUILDDIR)/doctrees
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "\033[0;32mBuilding PySCF docs\033[0m"
+
+	@echo "$(SPHINXBUILD) log in _build.log"
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html > _build.log 2> _build_err.log
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+html_parallel:
+	@echo
+	@echo "\033[0;32mBuilding PySCF docs\033[0m"
+
+	@echo "$(SPHINXBUILD) log in _build.log"
+	$(SPHINXBUILD) -b html -j auto $(ALLSPHINXOPTS) $(BUILDDIR)/html > _build.log 2> _build_err.log
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+api_docs:
+	@echo
+	bash scripts/generate_api_docs.sh
+	@echo
+
+html_full: api_docs
+	@echo
+	@echo "\033[0;32mBuilding PySCF docs\033[0m"
+
+	@echo "$(SPHINXBUILD) log in _build.log"
+	$(SPHINXBUILD) -b html -j auto $(ALLSPHINXOPTS) $(BUILDDIR)/html > _build.log 2> _build_err.log
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+gh_pages_setup:
+	@echo
+	bash scripts/gh_pages_setup.sh
+	@echo
+
+#
+# Less common commands
+#
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
@@ -175,4 +220,4 @@ xml:
 pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

README.md

@@ -2,28 +2,97 @@
   <img src="https://github.com/pyscf/pyscf-doc/blob/master/logo/pyscf-logo.png" height="80px"/>
 </div>
 
-PySCF documentation
+PySCF Documentation
 ===================
 
-Installation
-------------
+## Overview
 
-* Prerequisites
-    - [sphinx](https://pypi.org/project/Sphinx/)
-
-    - [sphinxcontrib-bibtex](https://pypi.org/project/sphinxcontrib-bibtex/) v1.0.0
+The PySCF documentation uses `sphinx-doc` and several associated extensions to generate static `html` files for the website.
+To simplify the command line work, we use `make` to manage all building here, see [the Building section](#building) below or just run `make help` for more details.
 
-    - Set `PYTHONPATH` to include the PySCF source directory; otherwise, uncomment `sys.path.append(os.path.abspath('path_to_pyscf'))` in [source/conf.py](source/conf.py).
+## Building the Docs Locally
 
-* Make HTML pages
+### Requirements
 
-        make html
+Pip install the following packages:
 
-    The resulting html files can be found in the \"build/html\" directory.
+- pyscf
+- sphinx
+- sphinx-material
+- sphinxcontrib-bibtex
+- nbsphinx
 
-How to contribute
------------------
+> Pro-tip: Use `pyscf-doc/requirements.txt` to install all prerequisite packages at once.
+
+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](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`.
+
+```bash
+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`.
+
+```bash
+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:
+
+```bash
+ python -m http.server --directory build/html
+```
+
+
+### Adding Content to GitHub Pages
+
+If you want to show the latest version of the docs on GitHub pages, build using then instructions above. Then from `pyscf-doc/source` run the following:
+
+```bash
+make gh_pages_setup
+```
+
+## How to Contribute
 
 1.  Add a rst file \"your\_method.rst\" in the [source/user](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](source/user.rst).
 2.  Add a rst file \"your\_module.rst\" in the [source/modules](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](https://github.com/pyscf/pyscf/blob/master/pyscf/dft/__init__.py) as an example.) Reference \"your\_module.rst\" in the \"toctree\" section in [source/modules.rst](source/modules.rst).
 3.  Optionally, one could also add a rst file \"your\_method\_develop.rst\" in the  [source/develop](source/develop/) directory where one provides more detailed descriptions of the implementation and advanced guidelines for using and further development of the module. Reference \"your\_method\_develop.rst\" in [source/develop.rst](source/develop.rst). 
+
+
+<!-- ## Adding Blog Posts
+
+Create a new `.md` file in `pyscf-doc/source/posts` and add the following header (modified for your post):
+
+```
+---
+blogpost: true
+date: February 1, 2021
+author: James Smith
+location: World
+category: Tutorial
+tags: HF, DFT, MCSCF
+language: English
+---
+```
+
+If you want to write a post in `.rst` that's fine too! Just use the following in your header:
+
+```
+:blogpost: true
+:date: Oct 10, 2020
+:author: Nabil Freij
+:location: World
+:category: Manual
+:language: English
+``` -->

requirements.txt

@@ -0,0 +1,6 @@
+pyscf
+sphinx
+ablog
+sphinx-material
+sphinxcontrib-bibtex
+nbsphinx

scripts/generate_api_docs.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+echo -e "\033[0;32mGenerating PySCF API Docs using sphinx-apidoc\033[0m"
+
+# Show the Python where PySCF is installed
+echo "Using $(which python)"
+
+# Get PySCF path
+PYSCF_PATH=$(python -c "import pyscf; print(pyscf.__path__[0])")
+
+if [ -z $PYSCF_PATH ]
+then
+    echo -e "\033[0;31mPySCF not found in current environment. Please switch environments or install it.\033[0m"
+else
+    echo -e "Found path to PySCF: \n\t${PYSCF_PATH}"
+fi
+
+# Run sphinx
+DESTINATION=source/pyscf_api_docs
+LOGFILE=_api_docs.log
+
+mkdir -p $DESTINATION
+echo -e "Output directory for API docs: \n\t$(pwd)/${DESTINATION}"
+echo -e "Log file:\n\t$(pwd)/${LOGFILE}"
+
+sphinx-apidoc -o $DESTINATION $PYSCF_PATH > ${LOGFILE}

scripts/gh_pages_setup.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+echo -e "\033[0;32mSetting up GitHub Pages docs directory\033[0m"
+
+echo -e "Deleting old docs directory"
+rm -r docs
+
+echo -e "Moving build/html to docs"
+mv build/html docs
+
+echo -e "Adding .nojekyll file to docs (so GitHub pages renders it correctly)"
+touch docs/.nojekyll

source/about.rst

@@ -0,0 +1,26 @@
+About
+=====
+
+The Team
+--------
+
+Board of directors
+""""""""""""""""""
+- Timothy Berkelbach, Columbia and Flatiron Institute
+- Garnet Chan, Caltech
+- Sandeep Sharma, UC Boulder
+- Alexander Sokolov, Ohio State
+- Qiming Sun, Tencent Quantum Laboratory
+
+Maintainers
+"""""""""""
+- Zhihao Cui, Caltech
+- Yang Gao, Caltech
+- Iliya Sabzevari, UC Boulder
+- James Smith, Flatiron Institute
+- Xiao Wang, Flatiron Institute
+
+Funding
+-------
+
+The development of PySCF has been and continues to be generously supported by a number of funding agencies. Most of the molecular quantum chemistry software infrastructure was developed with support from the US National Science Foundation, through grants CHE-1650436 and ACI-1657286. The periodic mean-field infrastructure was developed with support from ACI-1657286. The excited-state periodic coupled cluster methods were developed with support from the US Department of Energy, Office of Science, through the grants DE-SC0010530 and DE-SC0008624. Additional support for the extended-system methods has been provided by the Simons Foundation through the Simons Collaboration on the Many Electron Problem, a Simons Investigatorship in Theoretical Physics, the Princeton Center for Theoretical Science, and startup funds from Princeton University and the California Institute of Technology.

source/blog_wrapper.rst

@@ -0,0 +1,19 @@
+PySCF Blog
+=================================
+
+Here we post updates about the software and tutorials on how best to use PySCF.
+
+Shortcuts
+#########
+
+* :ref:`blog-tags`
+* :ref:`blog-archives`
+* :ref:`blog-categories`
+
+
+Recent Posts
+############
+
+.. postlist:: 5
+   :excerpts:
+