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

.gitignore

@@ -6,3 +6,4 @@ dist/
 .coverage
 coverage.xml
 docs/benchmark/AUDIO/
+docs/api/

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/audiofile.rst

@@ -0,0 +1,17 @@
+audiofile
+=========
+
+.. automodule:: audiofile
+
+.. autosummary::
+    :toctree:
+    :nosignatures:
+
+    read
+    write
+    bit_depth
+    channels
+    duration
+    samples
+    sampling_rate
+    convert_to_wav

docs/conf.py

@@ -1,8 +1,9 @@
 import configparser
 from datetime import datetime
+import shutil
 import os
-from subprocess import check_output
 
+import audeer
 
 config = configparser.ConfigParser()
 config.read(os.path.join('..', 'setup.cfg'))
@@ -13,21 +14,23 @@
 project = config['metadata']['name']
 copyright = f'2018-{datetime.now().year} audEERING GmbH'
 author = config['metadata']['author']
-# The x.y.z version read from tags
-try:
-    version = check_output(['git', 'describe', '--tags', '--always'])
-    version = version.decode().strip()
-except Exception:
-    version = '<unknown>'
-title = '{} Documentation'.format(project)
+version = audeer.git_repo_version()
+title = 'Documentation'
 
 
 # General -----------------------------------------------------------------
 
 master_doc = 'index'
 extensions = []
 source_suffix = '.rst'
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    'build',
+    'tests',
+    'Thumbs.db',
+    '.DS_Store',
+    'api-src',
+]
+templates_path = ['_templates']
 pygments_style = None
 extensions = [
     'jupyter_sphinx',
@@ -52,6 +55,11 @@
 copybutton_prompt_text = r'>>> |\.\.\. |\$ '
 copybutton_prompt_is_regexp = True
 
+# Disable auto-generation of TOC entries in the API
+# https://github.com/sphinx-doc/sphinx/issues/6316
+toc_object_entries = False
+
+
 # HTML --------------------------------------------------------------------
 
 html_theme = 'sphinx_audeering_theme'
@@ -64,3 +72,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

@@ -12,7 +12,7 @@
     :caption: API Documentation
     :hidden:
 
-    api
+    api/audiofile
 
 .. toctree::
     :caption: Development