TL: first big update on documentation, additional fixes

README.md

@@ -8,8 +8,8 @@
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/qmat?logo=pypi)](https://pypistats.org/packages/qmat)
 
 
-`qmat` is a python package to generate matrix coefficients related to Collocation methods, Spectral Deferred Corrections (SDC), 
-and more general multi-stages time-integration methods (like Runge-Kutta, etc ...).
+`qmat` is a python package to generate matrix coefficients related to Collocation methods, 
+Spectral Deferred Corrections (SDC), and more generally for Runge-Kutta methods.
 
 It allows to generate $Q$-coefficients for multi-stages methods (equivalent to Butcher tables) :
 

docs/conf.py

@@ -71,9 +71,17 @@
 autoapi_type = 'python'
 autoapi_dirs = ['../qmat']
 autoapi_file_patterns = ['*.py']
-autoapi_options = ['members', 'undoc-members']
+autoapi_options = [
+    'members', 'undoc-members', 
+    'show-inheritance-diagram',
+    'show-module-summary',
+    ]
 autoapi_python_class_content = 'both'
 autoapi_add_toctree_entry = False
+autoapi_ignore = ['*scripts*']
+autoapi_root = "api"
+
+autoapi_keep_files = False
 
 napoleon_use_param = False
 napoleon_use_keyword = False
@@ -140,6 +148,10 @@
 #
 # html_sidebars = {}
 
+html_theme_options = {
+    'globaltoc_maxdepth': 2,
+}
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/contributing.md

@@ -52,3 +52,13 @@ _A few base memo on how to develop this package ..._
     devdoc/versionUpdate
     devdoc/roadmap
 ```
+
+## Miscellaneous
+
+```{eval-rst}
+.. toctree::
+    :maxdepth: 1
+
+    CODE_OF_CONDUCT
+    SECURITY
+```

docs/index.rst

@@ -19,8 +19,8 @@ QMat Package
         <img alt="Codecov" src="https://codecov.io/gh/Parallel-in-Time/qmat/graph/badge.svg?token=MO0LDVH5NN">
     </a>
 
-`qmat` is a python package to generate matrix coefficients related to Collocation methods, Spectral Deferred Corrections (SDC), 
-and more general multi-stages time-integration methods (like Runge-Kutta, etc ...).
+`qmat` is a python package to generate matrix coefficients related to Collocation methods, 
+Spectral Deferred Corrections (SDC), and more generally for Runge-Kutta methods.
 
 It allows to generate :math:`Q`-coefficients for multi-stages methods (equivalent to Butcher tables) :
 
@@ -98,8 +98,7 @@ Doc Contents
     installation
     notebooks
     contributing
-    misc
-    API reference <autoapi/qmat/index>
+    API reference <api/qmat/index>
 
 Links
 =====

docs/notebooks.md

@@ -11,14 +11,16 @@ All tutorials are written in jupyter notebooks, that can be :
 
 Notebooks are categorized into three main sections :
 
-1. **Basic usage** : how to generate and use basic $Q$-coefficients and $Q_\Delta$ approximations
-2. **Extended usage** : additional features or `qmat`, like $S$-matrix, `hCoeffs`, `dTau`, etc ...
-3. **Advanced usage** : using `qmat` for generic non-linear ODE, multilevel SDC, PFASST, ...
+1. **Basic usage** : how to generate and use basic $Q$-coefficients and $Q_\Delta$ approximations, through a step-by-step tutorial going from generic Runge-Kutta methods to SDC for simple problems. 
+2. **Extended usage** : description of the additional features or `qmat`, like the $S$-matrix, 
+the `hCoeffs` and `dTau` coefficients, ... going deeper into SDC 
 
 
 ```{eval-rst}
-Basic usage
-===========
+Base usage
+==========
+
+📜 *From Butcher Tables to Spectral Deferred Corrections*
 
 .. toctree::
     :maxdepth: 1
@@ -29,18 +31,10 @@ Basic usage
 Extended usage
 ==============
 
-.. toctree::
-    :maxdepth: 1
-    :glob:
-
-    notebooks/1*
-
-Advanced usage
-==============
+📜 *Going deeper into SDC's understanding*
 
 .. toctree::
     :maxdepth: 1
     :glob:
 
-    notebooks/2*
-```
+    notebooks/1*

docs/notebooks/01_qCoeffs.ipynb

@@ -35,9 +35,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Use a generic function\n",
-    "\n",
-    "The quick easy way. First simply import :"
+    "## Use a generic function"
    ]
   },
   {
@@ -46,14 +44,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Base import\n",
     "from qmat import genQCoeffs"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Then use `genQCoeffs` to generate $Q$-coefficients like this :"
+    "Then you can generate $Q$-coefficients like this :"
    ]
   },
   {
@@ -118,8 +117,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Depending on its first given argument, `genQCoeffs` will use the associated $Q$-generator,\n",
-    "potentially passing keyword arguments to instantiate it (_e.g_ the `nNodes=4, nodeType=\"LEGENDRE\", quadType=\"RADAU-RIGHT\"` for collocation).\n",
+    "Depending on its first given argument, `genQCoeffs` uses the associated $Q$-generator,\n",
+    "potentially passing keyword arguments to instantiate it \n",
+    "(_e.g_ the `nNodes=4, nodeType=\"LEGENDRE\", quadType=\"RADAU-RIGHT\"` for collocation).\n",
     "If some generator arguments are missing or wrongly given, then a descriptive error is raised, for instance :"
    ]
   },
@@ -258,10 +258,9 @@
    "source": [
     "## Use generator objects\n",
     "\n",
-    "In case you want a more extended approach (_e.g_ keep the same generator and re-use it later, have several ones, ...), you can also directly use the generator classes. \n",
-    "Two ways to retrieve those :\n",
+    "You can also directly use the generator classes, either by\n",
     "\n",
-    "- import the generator directly from its submodule"
+    "- importing the generator directly from its submodule"
    ]
   },
   {
@@ -278,7 +277,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "- retrieve it with one of its aliases from the `Q_GENERATORS` dictionary"
+    "- retrieving it with one of its aliases from the `Q_GENERATORS` dictionary"
    ]
   },
   {
@@ -287,6 +286,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from qmat import Q_GENERATORS\n",
     "Generator = Q_GENERATORS[\"coll\"]\n",
     "coll = Generator(nNodes=4, nodeType=\"LEGENDRE\", quadType=\"RADAU-RIGHT\")"
    ]
@@ -328,7 +328,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "... or a `genCoeffs` method providing all coefficients (similarly as the `genQCoeffs` function) :"
+    "... or a `genCoeffs` method providing all coefficients, used similarly as the `genQCoeffs` function :"
    ]
   },
   {
@@ -344,7 +344,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next tutorial focuses on [building a Runge-Kutta type time-stepper using qmat ...](./02_rk.ipynb)"
+    "Then with those coefficient, you can [build a Runge-Kutta type time-stepper using qmat ...](./02_rk.ipynb)"
    ]
   }
  ],

qmat/__init__.py

@@ -1,5 +1,40 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+r"""
+**Main sub-packages** 📦
+
+- :class:`qcoeff` : to generate the :math:`Q`-coefficients (Butcher tables)
+- :class:`qdelta` : to generate :math:`Q_\Delta` approximations for :math:`Q` matrices
+
+**Utility modules** ⚙️
+
+- :class:`lagrange` : Barycentric polynomial approximations (integral, interpolation, derivation)
+- :class:`nodes` : generation of multiple types of quadrature nodes
+- :class:`sdc` : utility function to run SDC on simple problems
+- :class:`mathutils` : utility functions for math operations
+- :class:`utils` : utility functions for the whole package
+
+Examples
+--------
+>>> from qmat import genQCoeffs, genQDeltaCoeffs
+>>>
+>>> # Coefficients or specific collocation method
+>>> nodes, weights, Q = genQCoeffs(
+>>>     "Collocation", nNodes=4, nodeType="LEGENDRE", quadType="RADAU-RIGHT")
+>>>
+>>> # QDelta matrix from Implicit-Euler based SDC
+>>> QDelta = genQDeltaCoeffs("IE", nodes=nodes)
+>>>
+>>> # Butcher table of the classical explicit RK4 method
+>>> c, b, A = genQCoeffs("ERK4")
+
+
+>>> from qcoeff import Q_GENERATORS
+>>> print(Q_GENERATORS)     # list all available generator classes for Q coefficients
+
+>>> from qdelta import QDELTA_GENERATORS
+>>> print(QDELTA_GENERATORS)    # list all available generator classes for QDelta approximations
+"""
 from qmat.qcoeff import genQCoeffs, Q_GENERATORS
 from qmat.qdelta import genQDeltaCoeffs, QDELTA_GENERATORS
 

qmat/nodes.py

@@ -19,49 +19,41 @@ class NodesGenerator(object):
     Its implementation is fully inspired from a `book of W. Gautschi
     <https://doi.org/10.1093/oso/9780198506720.001.0001>`_.
 
-    Attributes
+    Parameters
     ----------
-    nodeType : str
-        The type of node distribution
-    quadType : str
-        The quadrature type
-    """
-    def __init__(self, nodeType='LEGENDRE', quadType='LOBATTO'):
-        """
-        Parameters
-        ----------
-        nodeType : str, optional
-            The type of node distribution, can be
+    nodeType : str, optional
+        The type of node distribution, can be
 
-            - EQUID : equidistant nodes
-            - LEGENDRE : node distribution from Legendre polynomials
-            - CHEBY-1 : node distribution from Chebychev polynomials (1st kind)
-            - CHEBY-2 : node distribution from Chebychev polynomials (2nd kind)
-            - CHEBY-3 : node distribution from Chebychev polynomials (3rd kind)
-            - CHEBY-4 : node distribution from Chebychev polynomials (4th kind)
+        - EQUID : equidistant nodes
+        - LEGENDRE : node distribution from Legendre polynomials
+        - CHEBY-1 : node distribution from Chebychev polynomials (1st kind)
+        - CHEBY-2 : node distribution from Chebychev polynomials (2nd kind)
+        - CHEBY-3 : node distribution from Chebychev polynomials (3rd kind)
+        - CHEBY-4 : node distribution from Chebychev polynomials (4th kind)
 
-            The default is 'LEGENDRE'.
+        The default is 'LEGENDRE'.
 
-        quadType : str, optional
-            The quadrature type, can be
+    quadType : str, optional
+        The quadrature type, can be
 
-            - GAUSS : inner point only, no node at boundary
-            - RADAU-LEFT : only left boundary as node
-            - RADAU-RIGHT : only right boundary as node
-            - LOBATTO : left and right boundary as node
+        - GAUSS : inner point only, no node at boundary
+        - RADAU-LEFT : only left boundary as node
+        - RADAU-RIGHT : only right boundary as node
+        - LOBATTO : left and right boundary as node
 
-            The default is 'LOBATTO'.
-        """
-
-        # Check argument validity
+        The default is 'LOBATTO'.
+    """
+    def __init__(self, nodeType='LEGENDRE', quadType='LOBATTO'):
         for arg, vals in zip(['nodeType', 'quadType'], [NODE_TYPES, QUAD_TYPES]):
             val = eval(arg)
             if val not in vals:
                 raise ValueError(f"{arg}='{val}' not implemented, must be in {vals}")
 
-        # Store attributes
         self.nodeType = nodeType
+        """Type of the node distribution"""
+
         self.quadType = quadType
+        """Quadrature type"""
 
 
     def getNodes(self, nNodes):