From a33632fda1112c0dd33a84ac306ceed0d017aa5a Mon Sep 17 00:00:00 2001 From: Hagen Wierstorf Date: Wed, 10 Jan 2024 10:16:15 +0100 Subject: [PATCH 1/3] DOC: use sphinx-apipages extension --- docs/_templates/autosummary/base.rst | 5 ----- docs/_templates/autosummary/class.rst | 19 ------------------- docs/_templates/autosummary/function.rst | 5 ----- docs/conf.py | 24 +----------------------- docs/requirements.txt | 1 + 5 files changed, 2 insertions(+), 52 deletions(-) delete mode 100644 docs/_templates/autosummary/base.rst delete mode 100644 docs/_templates/autosummary/class.rst delete mode 100644 docs/_templates/autosummary/function.rst diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst deleted file mode 100644 index 01a0408..0000000 --- a/docs/_templates/autosummary/base.rst +++ /dev/null @@ -1,5 +0,0 @@ -{{ name | escape | underline}} - -.. currentmodule:: {{ module }} - -.. auto{{ objtype }}:: {{ fullname }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst deleted file mode 100644 index f89a05d..0000000 --- a/docs/_templates/autosummary/class.rst +++ /dev/null @@ -1,19 +0,0 @@ -{{ objname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. autoclass:: {{ objname }} - -{% block methods %} -{%- for item in (all_methods + attributes)|sort %} - {%- if not item.startswith('_') or item in ['__call__', '__eq__', '__lt__', '__le__', '__gt__', '__ge__', '__repr__', '__str__'] %} - {%- 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 deleted file mode 100644 index 528f222..0000000 --- a/docs/_templates/autosummary/function.rst +++ /dev/null @@ -1,5 +0,0 @@ -{{ (name + '()') | escape | underline}} - -.. currentmodule:: {{ module }} - -.. auto{{ objtype }}:: {{ fullname }} diff --git a/docs/conf.py b/docs/conf.py index 04f2406..1ae6cdb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,3 @@ -import os -import shutil - import audeer @@ -21,16 +18,14 @@ '.DS_Store', 'api-src', ] -templates_path = ['_templates'] pygments_style = None extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', # support for Google-style docstrings - 'sphinx.ext.autosummary', 'sphinx_autodoc_typehints', 'sphinx_copybutton', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', + 'sphinx_apipages', ] intersphinx_mapping = { 'python': ('https://docs.python.org/3/', None), @@ -45,11 +40,6 @@ 'undoc-members': False, } -# 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' html_theme_options = { @@ -61,15 +51,3 @@ '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/requirements.txt b/docs/requirements.txt index a929f44..091c20d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ sphinx >=3.0.0 +sphinx-apipages sphinx-audeering-theme >=1.1.4 sphinx_autodoc_typehints sphinx-copybutton From df10ad50a0a74c4bb14cf144c8360bc6b166bdb8 Mon Sep 17 00:00:00 2001 From: Hagen Wierstorf Date: Wed, 10 Jan 2024 12:14:02 +0100 Subject: [PATCH 2/3] Require sphinx-apipages>=0.1.2 --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 091c20d..d3d48ed 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ sphinx >=3.0.0 -sphinx-apipages +sphinx-apipages >=0.1.2 sphinx-audeering-theme >=1.1.4 sphinx_autodoc_typehints sphinx-copybutton From c730999257ff599893a4a42741b816529176a2e7 Mon Sep 17 00:00:00 2001 From: Hagen Wierstorf Date: Wed, 10 Jan 2024 12:14:13 +0100 Subject: [PATCH 3/3] Specify hidden class methods to be included --- docs/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 1ae6cdb..b8400b9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,17 @@ autodoc_default_options = { 'undoc-members': False, } +apipages_hidden_methods = [ + '__call__', + '__eq__', + '__lt__', + '__le__', + '__gt__', + '__ge__', + '__repr__', + '__str__', +] + # HTML -------------------------------------------------------------------- html_theme = 'sphinx_audeering_theme'