Merge branch 'api-docs' into 'master'

Api docs

See merge request m300602/pyicon!24

README.md

@@ -56,3 +56,6 @@ Once, `cartopy` is installed in your environment:
 ```bash
 pip install git+https://gitlab.dkrz.de/m300602/pyicon.git
 ```
+
+## Developing
+When adding new functions, make sure to document them with a docstring. This should detail what the function does, the arguments and what type of objects it returns. Examples are encouraged. We use so-called "numpy" style docstrings which are then automatically rendered into the sphinx documentation. A guide to numpy style docstrings is available [here](https://numpydoc.readthedocs.io/en/latest/format.html) and they even produce some nice [examples](https://numpydoc.readthedocs.io/en/latest/example.html#example).
\ No newline at end of file

doc/api.rst

@@ -8,7 +8,32 @@ API for pyicon
 
 Some semi-automatically generate documentation about the pyicon API.
 
+
 .. automodule:: pyicon
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+pyicon.pyicon_accessor
+---------------------
+.. automodule:: pyicon.pyicon_accessor
+  :members:
+  :undoc-members:
+  :private-members:
+
+pyicon.pyicon_calc_xr
+---------------------
+.. automodule:: pyicon.pyicon_calc_xr
+  :members:
+  :undoc-members:
+  :private-members:
+
+pyicon.pyicon_calc
+---------------------
+.. automodule:: pyicon.pyicon_calc
+  :members:
+  :undoc-members:
+  :private-members:
 
 pyicon.pyicon_IconData
 ----------------------
@@ -16,8 +41,36 @@ pyicon.pyicon_IconData
 .. automodule:: pyicon.pyicon_IconData
   :members:
 
+pyicon.pyicon_params
+---------------------
+.. automodule:: pyicon.pyicon_params
+  :members:
+  :undoc-members:
+  :private-members:
+
 pyicon.pyicon_plotting
 ----------------------
 
 .. automodule:: pyicon.pyicon_plotting
   :members:
+
+pyicon.pyicon_simulation
+---------------------
+.. automodule:: pyicon.pyicon_simulation
+  :members:
+  :undoc-members:
+  :private-members:
+
+pyicon.pyicon_tb
+---------------------
+.. automodule:: pyicon.pyicon_tb
+  :members:
+  :undoc-members:
+  :private-members:
+
+pyicon.pyicon_thermo
+---------------------
+.. automodule:: pyicon.pyicon_thermo
+  :members:
+  :undoc-members:
+  :private-members:
\ No newline at end of file

doc/conf.py

@@ -18,8 +18,7 @@
 
 import os
 import sys
-# sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file
+sys.path.insert(0, os.path.abspath('..'))  # Source code dir relative to this file
  
 
 # -- General configuration ------------------------------------------------
@@ -35,12 +34,11 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.imgmath',
-#    'sphinx.ext.autosummary',
     'nbsphinx',
     'nbsphinx_link',
     'sphinx_copybutton',
-#    "IPython.sphinxext.ipython_directive",
-#    "IPython.sphinxext.ipython_console_highlighting",
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -54,6 +52,8 @@ source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
+autosummary_generate = True
+napoleon_numpy_docstring = True
 
 # !by_nils
 html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
@@ -165,6 +165,3 @@ texinfo_documents = [
      author, 'pyicon', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

doc/index.rst

@@ -27,10 +27,6 @@ Pyicon is hosted here: `<https://gitlab.dkrz.de/m300602/pyicon/>`_
    pyicon-view
    example_notebooks
    api
-
-..
-   example_notebooks
-
   
 Indices and tables
 ==================

pyicon/pyicon_calc_xr.py

@@ -206,19 +206,20 @@ def xr_crop_tgrid(ds_tg, ireg_c, verbose=1):
     ds_tg_cut: xarray Dataset, which contains (most of) the cropped grid variables.
 
 
-    Example usage
-    --------------
-    ds_tg = xr.open_mfdataset(fpath_tgrid)
-    clon = ds_tg.clon.compute().data * 180./np.pi
-    clat = ds_tg.clat.compute().data * 180./np.pi
-
-    lon_reg_3 = [6, 10]
-    lat_reg_3 = [-32, -30]
-    ireg_c = np.where(
-        (clon>lon_reg[0]) & (clon<=lon_reg[1]) & (clat>lat_reg[0]) & (clat<=lat_reg[1])
-    )[0]
-
-    ds_tg_cut = pyic.xr_crop_tgrid(ds_tg, ireg_c)
+    Examples
+    --------
+    
+    >>> ds_tg = xr.open_mfdataset(fpath_tgrid)
+    >>> clon = ds_tg.clon.compute().data * 180./np.pi
+    >>> clat = ds_tg.clat.compute().data * 180./np.pi
+    >>>
+    >>> lon_reg_3 = [6, 10]
+    >>> lat_reg_3 = [-32, -30]
+    >>> ireg_c = np.where(
+    ...    (clon>lon_reg[0]) & (clon<=lon_reg[1]) & (clat>lat_reg[0]) & (clat<=lat_reg[1])
+    ... )[0]
+    >>>
+    >>> ds_tg_cut = pyic.xr_crop_tgrid(ds_tg, ireg_c)
     """
 
     if "converted_tgrid" in ds_tg.attrs: