Finalize docs

README.md

@@ -2,10 +2,9 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 
-
 # atoMEC: Average-Atom Code for Matter under Extreme Conditions
-atoMEC is a python-based average-atom code for simulations of high energy density phenomena such as in warm dense matter. 
-It is designed as an open-source and modular python package. 
+atoMEC is a python-based average-atom code for simulations of high energy density phenomena such as in warm dense matter.
+It is designed as an open-source and modular python package.
 
 atoMEC uses Kohn-Sham density functional theory, in combination with an average-atom approximation,
 to solve the electronic structure problem for single-element materials at finite temperature.
@@ -21,14 +20,13 @@ This repository is structured as follows:
 ```
 
 
-
 ## Installation
 First, clone the atoMEC repository and ``cd`` into the main directory.
 
 * Recommended : using [pipenv](https://pypi.org/project/pipenv/)
 
   This route is recommended because `pipenv` automatically creates a virtual environment and manages dependencies.
-  
+
   1. First, install `pipenv` if it is not already installed, for example via `pip install pipenv` (or see [pipenv](https://pypi.org/project/pipenv/) for    installation instructions)
   2. Next, install `atoMEC`'s dependencies with `pipenv install`
   3. Use `pipenv shell` to activate the virtual environment and install atoMEC with `pip install -e .`
@@ -47,6 +45,19 @@ We welcome your contributions, please adhere to the following guidelines when co
 * Merges from `develop` to `master` are only done for code releases. This way we always have a clean `master` that reflects the current release
 * Code should be formatted using [black](https://pypi.org/project/black/) style
 
+### Build documentation locally (for developers)
+
+Install the prerequisites:
+```sh
+$ pip install -r docs/requirements.txt
+```
+
+1. Change into `docs/` folder.
+2. Run `make apidocs`.
+3. Run `make html`. This creates a `_build` folder inside `docs`. You may also want to use `make html SPHINXOPTS="-W"` sometimes. This treats warnings as errors and stops the output at first occurence of an error (useful for debugging rST syntax).
+4. Open `docs/_build/html/index.html`.
+5. `make clean` if required (e.g. after fixing erros) and building again.
+
 ## Developers
 ### Scientific Supervision
 - Attila Cangi ([Center for Advanced Systems Understanding](https://www.casus.science/))

atoMEC/__init__.py

@@ -1,3 +1,17 @@
+"""
+atoMEC: Average-atom code for matter under extreme conditions.
+
+Copyright (c) 2021 (in alphabetical order), Tim Callow, Attila Cangi, Eli Kraisler
+All rights reserved.
+
+atoMEC is a python-based average-atom code for simulations of high energy density phenomena such as in warm dense matter.
+Please see the README or the project wiki (https://atomec-project.github.io/atoMEC/) for more information.
+
+Classes
+-------
+Atom : the main object for atoMEC calculations, containing information about physical material properties
+"""
+
 # standard libraries
 from math import pi
 
@@ -13,8 +27,10 @@
 
 class Atom:
     r"""
-    The Atom class defines the main atom object containing the key information about the
-    atomic species, temperature, density etc
+    The principal object in atoMEC calculations which defines the physical material properties.
+
+    The `Atom` contains key information about the physical properties of the material
+    such as temperature, density, and charge. It does not contain any information about approximations or choices of model.
 
     Parameters
     ----------
@@ -82,7 +98,7 @@ def __init__(
 
     @property
     def species(self):
-        """str: the chemical symbol for the atomic species"""
+        """str: the chemical symbol for the atomic species."""
         return self._species
 
     @species.setter
@@ -91,19 +107,19 @@ def species(self, species):
 
     @property
     def at_chrg(self):
-        """int: the atomic charge Z"""
+        """int: the atomic charge Z."""
         chrg = self.species.atomic_number
         config.Z = chrg
         return chrg
 
     @property
     def at_mass(self):
-        """float: the atomic mass (in a.u.)"""
+        """float: the atomic mass (in a.u.)."""
         return self.species.atomic_weight
 
     @property
     def units_temp(self):
-        """str: the units of temperature"""
+        """str: the units of temperature."""
         return self._units_temp
 
     @units_temp.setter
@@ -112,7 +128,7 @@ def units_temp(self, units_temp):
 
     @property
     def temp(self):
-        """float: the electronic temperature in Hartree"""
+        """float: the electronic temperature in Hartree."""
         return self._temp
 
     @temp.setter
@@ -123,7 +139,7 @@ def temp(self, temp):
 
     @property
     def charge(self):
-        """int: the net charge of the atom"""
+        """int: the net charge of the atom."""
         return self._charge
 
     @charge.setter
@@ -132,13 +148,15 @@ def charge(self, charge):
 
     @property
     def nele(self):
-        """int: the number of electrons in the atom, given by the
-        sum of :obj:`at_chrg` and :obj:`charge`"""
+        """int: the number of electrons in the atom.
+
+        The total electron number is given by the sum of :obj:`at_chrg` and :obj:`charge`.
+        """
         return self.at_chrg + self._charge
 
     @property
     def units_radius(self):
-        """str: the units of the atomic radius"""
+        """str: the units of the atomic radius."""
         return self._units_radius
 
     @units_radius.setter
@@ -147,7 +165,7 @@ def units_radius(self, units_radius):
 
     @property
     def units_density(self):
-        """str: the units of the atomic density"""
+        """str: the units of the atomic density."""
         return self._units_density
 
     @units_density.setter
@@ -156,8 +174,11 @@ def units_density(self, units_density):
 
     @property
     def radius(self):
-        r"""float: radius of the Wigner-Seitz sphere, defined as :math:`a_i /2`,
-        where :math:`a_i` is the average inter-atomic distance"""
+        r"""float: radius of the Wigner-Seitz sphere.
+
+        The radius is defined as :math:`a_i /2`,
+        where :math:`a_i` is the average inter-atomic distance.
+        """
         return self._radius
 
     @radius.setter
@@ -169,7 +190,7 @@ def radius(self, radius):
 
     @property
     def density(self):
-        r"""float: the mass density of the material in units :math:`\mathrm{g\ cm}^{-3}`"""
+        r"""float: the mass density of the material in units :math:`\mathrm{g\ cm}^{-3}`."""
         return self._density
 
     @density.setter
@@ -181,6 +202,6 @@ def density(self, density):
 
     @property
     def info(self):
-        """str: formatted information about the :obj:`Atom`'s attributes"""
+        """str: formatted information about the :obj:`Atom`'s attributes."""
         # write output info
         return writeoutput.write_atomic_data(self)