DOC: split up into sub-pages per class/function (#54)

.gitignore

@@ -8,3 +8,4 @@ venv/
 .coverage*
 __init__.pyc
 coverage.xml
+docs/api/

audplot/core/api.py

@@ -38,7 +38,7 @@ def cepstrum(
     Returns:
         Image object
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -121,7 +121,7 @@ def confusion_matrix(
         ax: pre-existing axes for the plot.
             Otherwise, calls :func:`matplotlib.pyplot.gca()` internally
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -280,7 +280,7 @@ def detection_error_tradeoff(
     Returns:
         function to transform input values to standard normal derivate scale
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -365,7 +365,7 @@ def distribution(
         ax: pre-existing axes for the plot.
             Otherwise, calls :func:`matplotlib.pyplot.gca()` internally
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -442,7 +442,7 @@ def human_format(
         ValueError: if ``number`` :math:`\ge 1000^9`
             or ``number`` :math:`\le 1000^{-4}`
 
-    Example:
+    Examples:
         >>> human_format(12345)
         '12.3k'
         >>> human_format(1234567)
@@ -512,7 +512,7 @@ def scatter(
         ax: pre-existing axes for the plot.
             Otherwise, calls :func:`matplotlib.pyplot.gca()` internally
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -557,7 +557,7 @@ def series(
         ax: pre-existing axes for the plot.
             Otherwise, calls :func:`matplotlib.pyplot.gca()` internally
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -599,7 +599,7 @@ def signal(
         ax: pre-existing axes for the plot.
             Otherwise, calls :func:`matplotlib.pyplot.gca()` internally
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -649,7 +649,7 @@ def spectrum(
     Returns:
         Image object
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false
@@ -737,7 +737,7 @@ def waveform(
     Raises:
         RuntimeError: if signal has more than one channel
 
-    Example:
+    Examples:
         .. plot::
             :context: reset
             :include-source: false

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ fullname }}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,19 @@
+{{ objname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+{% block methods %}
+{%- for item in (all_methods + attributes)|sort %}
+    {%- if not item.startswith('_') or item in ['__call__'] %}
+        {%- if item in all_methods %}
+{{ (item + '()') | escape | underline(line='-') }}
+.. automethod:: {{ name }}.{{ item }}
+        {%- elif item in attributes %}
+{{ item | escape | underline(line='-') }}
+.. autoattribute:: {{ name }}.{{ item }}
+        {%- endif %}
+    {% endif %}
+{%- endfor %}
+{% endblock %}

docs/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ (name + '()') | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ fullname }}

docs/api-src/audplot.rst

@@ -0,0 +1,19 @@
+audplot
+=======
+
+.. automodule:: audplot
+
+.. autosummary::
+    :toctree:
+    :nosignatures:
+
+    cepstrum
+    confusion_matrix
+    detection_error_tradeoff
+    distribution
+    human_format
+    scatter
+    series
+    signal
+    spectrum
+    waveform

docs/conf.py

@@ -1,7 +1,9 @@
 import configparser
 from datetime import date
 import os
-import subprocess
+import shutil
+
+import audeer
 
 
 config = configparser.ConfigParser()
@@ -11,26 +13,26 @@
 author = config['metadata']['author']
 copyright = f'2020-{date.today().year} audEERING GmbH'
 project = config['metadata']['name']
-# The x.y.z version read from tags
-try:
-    version = subprocess.check_output(
-        ['git', 'describe', '--tags', '--always']
-    )
-    version = version.decode().strip()
-except Exception:
-    version = '<unknown>'
+version = audeer.git_repo_version()
 title = f'{project} Documentation'
 
 
 # General -----------------------------------------------------------------
 master_doc = 'index'
-extensions = []
 source_suffix = '.rst'
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    'api-src',
+    'build',
+    'tests',
+    'Thumbs.db',
+    '.DS_Store',
+]
+templates_path = ['_templates']
 pygments_style = None
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',  # support for Google-style docstrings
+    'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'sphinx_autodoc_typehints',
@@ -85,3 +87,15 @@
     'display_github': True,
 }
 html_title = title
+
+
+# Copy API (sub-)module RST files to docs/api/ folder ---------------------
+audeer.rmdir('api')
+audeer.mkdir('api')
+api_src_files = audeer.list_file_names('api-src')
+api_dst_files = [
+    audeer.path('api', os.path.basename(src_file))
+    for src_file in api_src_files
+]
+for src_file, dst_file in zip(api_src_files, api_dst_files):
+    shutil.copyfile(src_file, dst_file)

docs/index.rst

@@ -15,7 +15,7 @@
     :caption: API Documentation
     :hidden:
 
-    api
+    api/audplot
     genindex
 
 .. toctree::