diff --git a/.gitignore b/.gitignore index 59124f3..063a0ea 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ venv/ .coverage* __init__.pyc coverage.xml +docs/api/ diff --git a/audplot/core/api.py b/audplot/core/api.py index cc0daad..cf95540 100644 --- a/audplot/core/api.py +++ b/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 diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst new file mode 100644 index 0000000..01a0408 --- /dev/null +++ b/docs/_templates/autosummary/base.rst @@ -0,0 +1,5 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ fullname }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000..85d580f --- /dev/null +++ b/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 %} diff --git a/docs/_templates/autosummary/function.rst b/docs/_templates/autosummary/function.rst new file mode 100644 index 0000000..528f222 --- /dev/null +++ b/docs/_templates/autosummary/function.rst @@ -0,0 +1,5 @@ +{{ (name + '()') | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ fullname }} diff --git a/docs/api-src/audplot.rst b/docs/api-src/audplot.rst new file mode 100644 index 0000000..fa51899 --- /dev/null +++ b/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 diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index b2dfcb7..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,54 +0,0 @@ -audplot -======= - -.. automodule:: audplot - -cepstrum --------- - -.. autofunction:: cepstrum - -confusion_matrix ----------------- - -.. autofunction:: confusion_matrix - -detection_error_tradeoff ------------------------- - -.. autofunction:: detection_error_tradeoff - -distribution ------------- - -.. autofunction:: distribution - -human_format ------------- - -.. autofunction:: human_format - -scatter -------- - -.. autofunction:: scatter - -series ------- - -.. autofunction:: series - -signal ------- - -.. autofunction:: signal - -spectrum --------- - -.. autofunction:: spectrum - -waveform --------- - -.. autofunction:: waveform diff --git a/docs/conf.py b/docs/conf.py index 658a7e2..648ffb0 100644 --- a/docs/conf.py +++ b/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 = '' +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) diff --git a/docs/index.rst b/docs/index.rst index 0be76c9..29529e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,7 @@ :caption: API Documentation :hidden: - api + api/audplot genindex .. toctree::