Add template to make auto-generated module docs a bit less ugly

requests-cache · Apr 9, 2021 · 3883126 · 3883126
1 parent 70aafb5
commit 3883126
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 8 deletions.
diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- basename.split('.')[-1] | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,7 +21,11 @@
 templates_path = ['_templates']
 
 # Exclude the generated aiohttp_client_cache.rst, which will just contain top-level __init__ info
-exclude_patterns = ['_build', 'modules/aiohttp_client_cache.rst']
+exclude_patterns = [
+    '_build',
+    'modules/aiohttp_client_cache.rst',
+    'modules/aiohttp_client_cache.backends.rst',
+]
 
 # Sphinx extension modules
 extensions = [
@@ -59,8 +63,8 @@
 copybutton_prompt_is_regexp = True
 
 # Use apidoc to auto-generate rst sources
-apidoc_excluded_paths = ['api_docs.py']
-apidoc_extra_args = ['--private']
+apidoc_excluded_paths = ['forge_utils.py']
+apidoc_extra_args = ['--private', '--templatedir=_templates']
 apidoc_module_dir = PACKAGE_DIR
 apidoc_module_first = True
 apidoc_output_dir = 'modules'

diff --git a/docs/index.rst b/docs/index.rst
@@ -12,11 +12,11 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   reference
-   history
-   contributing
+    reference
+    history
+    contributing
 
 
 Indices and tables

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -9,4 +9,11 @@ API Reference
     :glob:
     :titlesonly:
 
-    modules/*
+    modules/aiohttp_client_cache.[!b]*
+
+.. toctree::
+    :caption: Backend Modules
+    :glob:
+    :titlesonly:
+
+    modules/aiohttp_client_cache.backends.*