diff --git a/.gitignore b/.gitignore index 9b9d187f..8252c358 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ dist/ .coverage coverage.xml docs/benchmark/AUDIO/ +docs/api/ diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst new file mode 100644 index 00000000..01a0408f --- /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 00000000..85d580f4 --- /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 00000000..528f2227 --- /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/audiofile.rst b/docs/api-src/audiofile.rst new file mode 100644 index 00000000..05e73e2e --- /dev/null +++ b/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 diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index d223b9cb..00000000 --- a/docs/api.rst +++ /dev/null @@ -1,55 +0,0 @@ -audiofile -========= - -.. automodule:: audiofile - -.. autosummary:: - - read - write - bit_depth - channels - duration - samples - sampling_rate - convert_to_wav - -read ----- - -.. autofunction:: read - -write ------ - -.. autofunction:: write - -bit_depth ---------- - -.. autofunction:: bit_depth - -channels --------- - -.. autofunction:: channels - -duration --------- - -.. autofunction:: duration - -samples -------- - -.. autofunction:: samples - -sampling_rate -------------- - -.. autofunction:: sampling_rate - -convert_to_wav --------------- - -.. autofunction:: convert_to_wav diff --git a/docs/conf.py b/docs/conf.py index 9d0808d6..a82ea021 100644 --- a/docs/conf.py +++ b/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,13 +14,8 @@ 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 = '' -title = '{} Documentation'.format(project) +version = audeer.git_repo_version() +title = 'Documentation' # General ----------------------------------------------------------------- @@ -27,7 +23,14 @@ 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) diff --git a/docs/index.rst b/docs/index.rst index 22cfc85b..c1aeba43 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ :caption: API Documentation :hidden: - api + api/audiofile .. toctree:: :caption: Development