update doc, add readthedocs.yml

.readthedocs.yml

@@ -0,0 +1,8 @@
+sphinx:
+  configuration: doc/conf.py
+
+python:
+  version: 3.7
+  install:
+    -requirements: doc/requirements.txt
+

doc/conf.py

@@ -10,15 +10,15 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'pyzfs'
-copyright = '2020, He Ma, Marco Govoni, Giulia Galli'
+copyright = '2020, University of Chicago'
 author = 'He Ma, Marco Govoni, Giulia Galli'
 
 
@@ -27,8 +27,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+master_doc = 'index'
+
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
 
+autodoc_mock_imports = ["mpi4py"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/documentation.rst

@@ -3,7 +3,7 @@
 Code documentation
 ==================
 
-**pyzfs** detailed documentation.
+**PyZFS** code documentation.
 
 ZFS
 ------

doc/index.rst

@@ -3,12 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pyzfs's documentation!
+Welcome to PyZFS's documentation!
 =================================
 
-**pyzfs** is an MPI-parallelized Python code for the first-principles calculation of the spin-spin zero-field-splitting (ZFS) tensor based on wavefunctions obtained from density functional theory (DFT) calculations.
+**PyZFS** is an MPI-parallelized Python code for the first-principles calculation of the spin-spin zero-field-splitting (ZFS) tensor based on wavefunctions obtained from density functional theory (DFT) calculations.
 
-**pyzfs** can work with wavefunctions generated by various plane-wave pseudopotential DFT codes including [**Quantum Espresso**](https://www.quantum-espresso.org/) and [**Qbox**](http://qboxcode.org/). **pyzfs** also supports the standard cube file format. **pyzfs** computes the spin-spin ZFS tensor from normalized pseudo-wavefunctions without projected-augmented-wave type corrections and is designed to be scalable to large calculations. For instance, **pyzfs** has been applied to study spin-defects in semiconductors using supercells containing thousands of valence electrons.
+**PyZFS** can work with wavefunctions generated by various plane-wave pseudopotential DFT codes including [**Quantum Espresso**](https://www.quantum-espresso.org/) and [**Qbox**](http://qboxcode.org/). **PyZFS** also supports the standard cube file format. **PyZFS** computes the spin-spin ZFS tensor from normalized pseudo-wavefunctions without projected-augmented-wave type corrections and is designed to be scalable to large calculations. For instance, **PyZFS** has been applied to study spin-defects in semiconductors using supercells containing thousands of valence electrons.
 
 --------
 
@@ -23,11 +23,11 @@ Welcome to pyzfs's documentation!
 .. glossary::
 
    :ref:`installation`
-      Instructions on how to install the **pyzfs** package.
+      Instructions on how to install the **PyZFS** package.
 
    :ref:`tutorial`
-      Demonstration of usage of **pyzfs** with wavefunctions from various DFT codes.
+      Demonstration of usage of **PyZFS** with wavefunctions from various DFT codes.
 
    :ref:`documentation`
-      Detailed documentation of the **pyzfs** package.
+      Detailed documentation of the **PyZFS** package.
 

doc/installation.rst

@@ -4,22 +4,35 @@
 Installation
 ============
 
-**pyzfs** can be installed with **pip** by running following command in the project root folder containing **setup.py**
+**PyZFS** uses the **mpi4py** package for parallelization. An existing MPI implementation (e.g. **MPICH** or **OpenMPI**) is required to install **mpi4py** and **PyZFS**. Many supercomputers provide modules for pre-compiled MPI implementations. To install MPI manually (taking **MPICH** as example), execute the following command on Linux
+
+.. code:: bash
+
+   $ sudo apt-get install mpich libmpich-dev
+
+or execute the following command on Mac
+
+.. code:: bash
+
+   $ brew install mpich
+
+**PyZFS** can be installed with **pip** by executing the following command in the project root folder containing **setup.py**
 
 .. code:: bash
 
    $ pip install .
 
-To install **pyzfs** in editable mode
+To install **PyZFS** in editable mode
 
 .. code:: bash
 
    $ pip install -e .
 
-**pyzfs** is designed to be compatible with both Python 2 and Python 3, and depends on the following packages:
+**PyZFS** is designed to be compatible with both Python 2 and Python 3, and depends on the following packages:
    - ``numpy``
    - ``scipy``
    - ``mpi4py``
+   - ``h5py``
    - ``ase``
    - ``lxml``
 

doc/requirements.txt

@@ -0,0 +1,6 @@
+numpy
+scipy
+h5py
+ase
+lxml
+

doc/tutorial.rst

@@ -4,7 +4,7 @@
 Tutorial
 ============
 
-After installation, **pyzfs** can be executed in two manners:
+After installation, **PyZFS** can be executed in two manners:
 
 1. Construct WavefunctionLoader and ZFSCalculation loader from within Python terminal or Jupyter notebook, and call ZFSCalculation.solve to perform the calculation.
 
@@ -24,7 +24,7 @@ For parallel execution, use the following command
 
    $ mpiexec [-n num_of_processes] python -m pyzfs.exec.runzfs [--flags]
 
-where `num_of_processes` is the number of processes. **pyzfs** distributes the calculations on a square grid of processes. If `num_of_processes` is not a square number, **pyzfs** will use the largest square number of processes smaller than `num_of_processes` for calculations.
+where `num_of_processes` is the number of processes. **PyZFS** distributes the calculations on a square grid of processes. If `num_of_processes` is not a square number, **PyZFS** will use the largest square number of processes smaller than `num_of_processes` for calculations.
 
 Acceptable flags [`--flags`] are listed below, for detailed explanation see `pyzfs.exec.runzfs.py`.
 
@@ -48,9 +48,9 @@ Some example execution commands with flags:
 
 .. code:: bash
 
-mpiexec python -m pyzfs.exec.runzfs --wfcfmt qeh5 --prefix pwscf
+   $ mpiexec python -m pyzfs.exec.runzfs --wfcfmt qeh5 --prefix pwscf
 
 .. code:: bash
 
-mpiexec python -m pyzfs.exec.runzfs --wfcfmt qbox --filename gs.xml
+   $ mpiexec python -m pyzfs.exec.runzfs --wfcfmt qbox --filename gs.xml