Adding documentation

The documentation of iDEA consists of two main parts:

• the doc/ folder, which contains documentation written in the intuitive reStructuredText (reST) format
• python docstrings in the iDEA source code that document the functionality of its modules, classes, functions, etc. (specifically, we follow the numpy convention)

Both are important and you are most welcome to contribute to either of them.

In order to generate a browseable HTML version of the documentation (which is displayed on the iDEA home page), we use a tool called Sphinx, which also takes care of producing a documentation of the source code (the API documentation).

Once you are done editing the documentation, produce an updated HTML version

cd doc
bash make_doc.sh

See Generating the documentation for details.

A short reST demo

• Write your mathematical formulae using LaTeX, in line \(\exp(-i2\pi)\) or displayed

  \[f(x) = \int_0^\infty \exp\left(\frac{x^2}{2}\right)\,dx\]

• You want to refer to a particular function or class? You can!

  iDEA.RE.calculate_ground_state(pm, approx, density_approx, v_ext, K)

  Calculates the exact ground-state Kohn-Sham potential by solving the ground-state Kohn-Sham equations and iteratively correcting v_ks. The exact ground-state Kohn-Sham eigenfunctions, eigenenergies and electron density are then calculated.

  \[V_{\mathrm{KS}}(x) \rightarrow V_{\mathrm{KS}}(x) + \mu[n_{\mathrm{KS}}^{p}(x)-n_{\mathrm{approx}}^{p}(x)]\]

  Parameters:

  pm : object

  Parameters object

  approx : string

  The approximation used to calculate the electron density

  density_approx : array_like

  1D array of the ground-state electron density from the approximation, indexed as density_approx[space_index]

  v_ext : array_like

  1D array of the unperturbed external potential, indexed as v_ext[space_index]

  K : array_like

  2D array of the kinetic energy matrix, index as K[band,space_index]

  returns array_like and array_like and array_like and array_like and Boolean

  1D array of the ground-state Kohn-Sham potential, indexed as v_ks[space_index]. 1D array of the ground-state Kohn-Sham electron density, indexed as density_ks[space_index]. 2D array of the ground-state Kohn-Sham eigenfunctions, indexed as wavefunctions_ks[space_index,eigenfunction]. 1D array containing the ground-state Kohn-Sham eigenenergies, indexed as energies_ks[eigenenergies]. Boolean - True if file containing exact Kohn-Sham potential is found, False if file is not found.

• Add images/plots to iDEA/doc/_static and then include them

  

• Check out the source of any page via the link in the bottom right corner.

reST source of this page:

********************
Adding documentation
********************

The documentation of iDEA consists of two main parts:

 * the :code:`doc/` folder, which contains documentation written in the intuitive
   `reStructuredText (reST) <http://sphinx-doc.org/rest.html#rst-primer>`_ format
 * `python docstrings <https://www.python.org/dev/peps/pep-0257/>`_ in the iDEA
   source code that document the functionality of its modules, classes, functions,
   etc. (specifically, we follow the
   `numpy convention <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_)

Both are important and you are most welcome to contribute to either of them.

In order to generate a browseable HTML version of the documentation (which is
displayed on the iDEA home page), we use a tool called
`Sphinx <http://sphinx-doc.org>`_, which also takes care of producing a
documentation of the source code (the API documentation).

Once you are done editing the documentation, produce an updated HTML version

.. code-block:: bash

    cd doc
    bash make_doc.sh 

See :ref:`generate-documentation` for details.


A short reST demo
------------------


  * Write your mathematical formulae using LaTeX, 
    in line :math:`\exp(-i2\pi)` or displayed

    .. math:: f(x) = \int_0^\infty \exp\left(\frac{x^2}{2}\right)\,dx

  * You want to refer to a particular function or class? You can!

    .. autofunction:: iDEA.RE.calculate_ground_state
       :noindex:
  * Add images/plots to ``iDEA/doc/_static`` and then include them

    .. image:: ../_static/logo.png

  * Check out the source of any page via the link 
    in the bottom right corner.

|  

reST source of this page:

.. literalinclude:: documentation.rst