update documentation to use autosummary

* remove manual module reference files * move hdf5 structure reference to guide * fix various doc strings * remove very old update_archive python script for triqs 1.2 * refine main documentation.rst file -> better overview
70akaline · Mar 2, 2022 · c4db7e6 · c4db7e6
1 parent 9a51232
commit c4db7e6
Show file tree

Hide file tree

Showing 30 changed files with 122 additions and 320 deletions.
diff --git a/doc/_templates/autosummary_module_template.rst b/doc/_templates/autosummary_module_template.rst
@@ -1,4 +1,4 @@
-{{ fullname | escape | underline}}
+{{ name | escape | underline}}
 
 .. automodule:: {{ fullname }}
 

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -76,7 +76,7 @@ html_theme_options = {
     # Toc options
     'collapse_navigation': False,
     'sticky_navigation': True,
-    'navigation_depth': 5,
+    'navigation_depth': 4,
     'includehidden': True,
     'titles_only': False
 }

diff --git a/doc/documentation.rst b/doc/documentation.rst
@@ -9,7 +9,7 @@ Basic notions
 -------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    basicnotions/first
    basicnotions/dft_dmft
@@ -23,6 +23,7 @@ Construction of local orbitals from DFT
    :maxdepth: 2
 
    guide/conversion
+   h5structure
 
 
 DFT+DMFT
@@ -38,7 +39,7 @@ Advanced Topics
 ---------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    guide/blockstructure
    guide/BasisRotation
@@ -48,7 +49,7 @@ Postprocessing
 --------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    guide/analysis
    guide/transport
@@ -59,16 +60,18 @@ Reference manual
 
 This is the reference manual for the python routines.
 
-.. toctree::
-   :maxdepth: 2
+.. autosummary::
+   :recursive:
+   :toctree: _python_api
+   :template: autosummary_module_template.rst
+
+   block_structure
+   converters
+   sumk_dft
+   sumk_dft_tools
+   symmetry
+   trans_basis
 
-   reference/h5structure
-   reference/converters
-   reference/sumk_dft
-   reference/sumk_dft_tools
-   reference/symmetry
-   reference/transbasis
-   reference/block_structure
 
 
 FAQs

diff --git a/doc/guide/conv_generalhk.rst b/doc/guide/conv_generalhk.rst
@@ -95,6 +95,6 @@ where :file:`hkinputfile` is the name of the input file described
 above. This produces the hdf file that you need for a DMFT calculation.
 
 For more options of this converter, have a look at the
-:ref:`refconverters` section of the reference manual.
+:py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 
diff --git a/doc/guide/conv_vasp.rst b/doc/guide/conv_vasp.rst
@@ -17,10 +17,10 @@ Hubbard-like model Hamiltonian. Resulting in lattice object stored in `SumkDFT`.
 The implementation is presented in `M. Schüler et al. 2018 J. Phys.: Condens.
 Matter 30 475901 <https://doi.org/10.1088/1361-648X/aae80a>`_.
 
-The interface consists of two parts, :ref:`PLOVASP<refPLOVASP>`, a collection of
+The interface consists of two parts, :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>`, a collection of
 python classes and functions converting the raw VASP output to proper projector
-functions, and the python based :ref:`VaspConverter<refVASPconverter>`, which
-creates a h5 archive from the :ref:`PLOVASP<refPLOVASP>` output readable by
+functions, and the python based :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>`, which
+creates a h5 archive from the :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` output readable by
 `SumkDFT`. Therefore, the conversion consist always of two steps.
 
 Here, we will present a guide how the interface `can` be used to create input for a DMFT calculation, using SrVO3 as an example. Full examples can be found in the :ref:`tutorial section of DFTTools<tutorials>`.
@@ -134,7 +134,7 @@ described above and it must be chosen independently of the energy range given by
 PLOVASP: converting VASP output
 --------------------------------
 
-:ref:`PLOVASP<refPLOVASP>` is a collection of python functions and classes, post-processing the raw VASP `LOCPROJ` output creating proper projector functions.
+:py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` is a collection of python functions and classes, post-processing the raw VASP `LOCPROJ` output creating proper projector functions.
 
 The following VASP files are used by PLOVASP:
   * PROJCAR, LOCPROJ: raw projectors generated by VASP-PLO interface
@@ -176,12 +176,12 @@ or embedded in a python script as::
     # Generate and store PLOs
     plo_converter.generate_and_output_as_text('plo.cfg', vasp_dir='./')
 
-This will create the xml files `vasp.ctrl` and `vasp.pg1` containing the orthonormalized projector functions readable by the :ref:`VaspConverter<refVASPconverter>`. Moreover, `PLOVASP` will output important information of the orthonormalization process, such as the density matrix of the correlated shell and the local Hamiltonian.
+This will create the xml files `vasp.ctrl` and `vasp.pg1` containing the orthonormalized projector functions readable by the :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>`. Moreover, :py:mod:`PLOVASP<triqs_dft_tools.converters.plovasp>` will output important information of the orthonormalization process, such as the density matrix of the correlated shell and the local Hamiltonian.
 
 Running the VASP converter
 -------------------------------------
 
-The actual conversion to a h5-file is performed with the orthonormalized projector functions readable by the :ref:`VaspConverter<refVASPconverter>` in the same fashion as with the other `DFTTools` converters::
+The actual conversion to a h5-file is performed with the orthonormalized projector functions readable by the :py:mod:`VaspConverter<triqs_dft_tools.converters.vasp>` in the same fashion as with the other `DFTTools` converters::
 
     from triqs_dft_tools.converters.vasp import *
     Converter = VaspConverter(filename = 'vasp')
@@ -394,12 +394,14 @@ in the header. One can either copy the Fermi energy manually there after a succe
 VASP run, or modify the VASP source code slightly, by replacing the following line in
 `locproj.F` (around line 695):
 ::
+
   <   WRITE(99,'(4I6,"  # of spin, # of k-points, # of bands, # of proj" )') NS,NK,NB,NF
   ---
   >   WRITE(99,'(4I6,F12.7,"  # of spin, # of k-points, # of bands, # of proj, Efermi" )') W%WDES%NCDIJ,NK,NB,NF,EFERMI
 
 Now one needs to pass additionally the variable `EFERMI` to the function, by changing (at arount line 560): 
 ::
+
   <   SUBROUTINE LPRJ_WRITE(IU6,IU0,W)
   ---
   >   SUBROUTINE LPRJ_WRITE(IU6,IU0,W,EFERMI)
@@ -408,6 +410,7 @@ Now one needs to pass additionally the variable `EFERMI` to the function, by cha
 Next, we need to pass this option when calling from `electron.F` and `main.F` 
 (just search for LPRJ_WRITE in the files) and change all occurences as follows: 
 ::
+
   <   CALL LPRJ_WRITE(IO%IU6, IO%IU0, W)
   ---
   >   CALL LPRJ_WRITE(IO%IU6, IO%IU0, W, EFERMI)
@@ -424,13 +427,16 @@ Furthermore, there is a bug in `fileio.F` around line 1710 where VASP tries to
 print "reading the density matrix from Gamma". This should be done only by the
 master node, and VASP gets stuck sometimes. Adding a
 ::
+
   IF (IO%IU0>=0) THEN
   ...
   ENDIF
+
 statement resolves this issue. A similar problem occurs, when VASP writes the
 `OSZICAR` file and a buffer is stuck. Adding a `flush` to the buffer in
 `electron.F` around line 580 after
 ::
+
   CALL STOP_TIMING("G",IO%IU6,"DOS")
   flush(17)
   print *, ' '

diff --git a/doc/guide/conv_wien2k.rst b/doc/guide/conv_wien2k.rst
@@ -128,7 +128,7 @@ example, the :program:`Wien2k` naming convention is that all files have the
 same name, but different extensions, :file:`case.*`. The constructor opens
 an hdf5 archive, named :file:`case.h5`, where all relevant data will be
 stored. For other parameters of the constructor please visit the
-:ref:`refconverters` section of the reference manual.
+:py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 After initializing the interface module, we can now convert the input
 text files to the hdf5 archive by::
@@ -181,7 +181,7 @@ and convert the input for :class:`SumkDFTTools <dft.sumk_dft_tools.SumkDFTTools>
 
 After having converted this input, you can further proceed with the
 :ref:`analysis`. For more options on the converter module, please have
-a look at the :ref:`refconverters` section of the reference manual.
+a look at the :py:mod:`Converters <triqs_dft_tools.converters>` section of the reference manual.
 
 Data for transport calculations
 -------------------------------

diff --git a/doc/guide/soc.rst b/doc/guide/soc.rst
@@ -39,7 +39,7 @@ Note that in presence of SOC, it is not possible to project only onto the :math:
 Treatment of SOC in Elk
 -------------------------
 
-First, a Elk calculation including SOC has to be performed. For details, we refer the reader to the SOC Elk examples in Elk's example directory and `Elk manual <https//elk.sourceforge.net/elk.pdf>`_ for further information about the input flags. Then the projectors can be generated using the ``wanproj`` input flag in the same format as in :ref:`conv_elk`. Like in Wien2k, you cannot project only onto the :math:`t_{2g}` subshell because it is not an irreducible representation in SOC calculations. 
+First, a Elk calculation including SOC has to be performed. For details, we refer the reader to the SOC Elk examples in Elk's example directory and `Elk manual <https//elk.sourceforge.net/elk.pdf>`_ for further information about the input flags. Then the projectors can be generated using the ``wanproj`` input flag in the same format as in :ref:`convElk`. Like in Wien2k, you cannot project only onto the :math:`t_{2g}` subshell because it is not an irreducible representation in SOC calculations. 
 
 After generating the projectors
 -------------------------------

diff --git a/doc/reference/h5structure.rst → doc/h5structure.rst b/doc/reference/h5structure.rst → doc/h5structure.rst
@@ -1,9 +1,9 @@
 .. _hdfstructure:
 
-hdf5 structure
-==============
+standardized hdf5 structure
+===========================
 
-All the data is stored using the hdf5 standard, as described also in the
+All the DFT input data is stored using the hdf5 standard, as described also in the
 documentation of the TRIQS package itself. In order to do a DMFT calculation,
 using input from DFT applications, a converter is needed on order to provide
 the necessary data in the hdf5 format.

diff --git a/doc/reference/block_structure.rst b/doc/reference/block_structure.rst
diff --git a/doc/reference/converters.rst b/doc/reference/converters.rst
diff --git a/doc/reference/sumk_dft.rst b/doc/reference/sumk_dft.rst
diff --git a/doc/reference/sumk_dft_tools.rst b/doc/reference/sumk_dft_tools.rst
diff --git a/doc/reference/symmetry.rst b/doc/reference/symmetry.rst
diff --git a/doc/reference/transbasis.rst b/doc/reference/transbasis.rst
diff --git a/doc/tutorials.rst b/doc/tutorials.rst
@@ -1,5 +1,3 @@
-.. module:: triqs_dft_tools
-
 .. _tutorials:
 
 Tutorials

diff --git a/python/triqs_dft_tools/block_structure.py b/python/triqs_dft_tools/block_structure.py
@@ -21,7 +21,9 @@
 # TRIQS. If not, see <http://www.gnu.org/licenses/>.
 #
 ##########################################################################
-
+"""
+Block structure class and helper functions
+"""
 
 import copy
 import numpy as np
@@ -38,6 +40,11 @@ class BlockStructure(object):
     This class contains information about the structure of the solver
     and sumk Green functions and the mapping between them.
 
+    Do not write the individual elements of this class to a HDF file,
+    as they belong together and changing one without the other can
+    result in unexpected results. Always write the BlockStructure
+    object as a whole.
+
     Parameters
     ----------
     gf_struct_sumk : list of list of tuple

diff --git a/python/triqs_dft_tools/converters/__init__.py b/python/triqs_dft_tools/converters/__init__.py
@@ -19,6 +19,9 @@
 # TRIQS. If not, see <http://www.gnu.org/licenses/>.
 #
 ##########################################################################
+"""
+module containing all available converters for DFTTools
+"""
 
 from .wien2k import Wien2kConverter
 from .hk import HkConverter