add module comments and refactor api docs

Author: antheas

docs/source/_templates/autosummary/module.rst

@@ -3,7 +3,7 @@
 .. rubric:: Description
 
 .. automodule:: {{ fullname }}
-
+   
    {% block functions %}
    {% if functions %}
    .. rubric:: Functions

docs/source/_templates/autosummary/pasteur.rst

@@ -0,0 +1,93 @@
+{{ fullname | escape | underline }}
+
+.. rubric:: Description
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% set pasteur_attr = ["pasteur.attribute","pasteur.hierarchy","pasteur.table"] %}
+{% set pasteur_modules = ["pasteur.module", "pasteur.dataset","pasteur.view","pasteur.transform","pasteur.encode","pasteur.synth","pasteur.metric"] %}
+{% set pasteur_misc = ["pasteur.kedro","pasteur.utils","pasteur.extras","pasteur.cli"] %}
+
+.. rubric:: Module-System Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in pasteur_modules %}
+   {{ item }}
+{%- endfor %}
+
+.. rubric:: Transformation-Related Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in pasteur_attr %}
+   {{ item }}
+{%- endfor %}
+
+{% block modules %}
+{% if modules|length > pasteur_modules|length + pasteur_misc|length + pasteur_attr|length %}
+.. rubric:: Other Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in modules %}
+   {% if item not in pasteur_modules and item not in pasteur_attr and item not in pasteur_misc %}
+      {{ item }}
+   {% endif %}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+.. rubric:: Miscellaneous Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in pasteur_misc %}
+   {{ item }}
+{%- endfor %}

docs/source/index.rst

@@ -22,7 +22,7 @@ API documentation
 .. autosummary::
    :toctree: api
    :caption: API documentation
-   :template: autosummary/module.rst
+   :template: autosummary/pasteur.rst
    :recursive:
 
    pasteur

src/pasteur/encode.py

@@ -1,3 +1,5 @@
+""" Provides the base definition for Encoder modules"""
+
 import pandas as pd
 
 from .attribute import Attribute

src/pasteur/extras/metrics/models/__init__.py

@@ -1,3 +1,7 @@
+""" This module provides Model based metrics. 
+
+Currently, this translates to classifiers. """
+
 from __future__ import annotations
 
 from .base import BaseModel, ModelMetric

src/pasteur/kedro/__init__.py

@@ -1 +1 @@
-""" This sub-package contains all kedro-related logic. """
+""" This module contains all kedro-related logic. """

src/pasteur/kedro/cli.py

@@ -1,3 +1,7 @@
+""" In this module, all Pasteur related cli commands are defined.
+
+You can access them through `pasteur <command>` or `kedro <command>`. """
+
 import logging
 from typing import Any, Iterable
 

src/pasteur/kedro/dataset.py

@@ -1,3 +1,8 @@
+""" This module provides kedro datasets that have been customized to suit Pasteur's needs.
+
+The most notable additions are that the datasets lazy load data through `PartitionedDataset`
+and can partition save data through custom `Node` return types. """
+
 import logging
 import os
 import re

src/pasteur/kedro/hooks/__init__.py

@@ -1,3 +1,11 @@
+""" Pasteur ships with two hooks: one that dynamically creates the synthetic
+data pipelines and datasets, and one that manages Mlflow runs.
+
+The classes of those hooks are provided through `PasteurHook`, `MlflowTrackingHook`.
+
+In addition, instances of those hooks are provided in `pasteur` and `mlflow`,
+which are registered as Kedro entrypoints. """
+
 from ..utils import get_pasteur_modules
 
 modules = get_pasteur_modules()

src/pasteur/kedro/ipython.py

@@ -1,3 +1,4 @@
+""" This module extends Kedro's ipython functionality. """
 from pathlib import Path
 
 from IPython import get_ipython