only override autosummary for accessor-related templates (#67)

* only override autosummary for accessor-related templates

* create a list of known templates

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* import from the new `templates` module

* compare against the list of known templates

* add a entry to demonstrate that custom templates still work

* actually find all templates

* include all directory names in the main templates directory

Co-authored-by: Keewis <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/_templates/custom-template.rst

@@ -0,0 +1,32 @@
+{{ fullname }}
+{{ underline }}
+
+.. autoclass:: {{ [module, objname] | join('.') }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated/
+   {% for item in methods %}
+      {% if item != "__init__" %}
+         ~{{ [module, name] | join('.') }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated/
+   {% for item in attributes %}
+      ~{{ [module, name] | join('.') }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/examples.rst

@@ -75,3 +75,17 @@ become:
    :template: autosummary/accessor_method.rst
 
    Example.test2.sub.func
+
+Different templates still work:
+
+.. literalinclude:: examples.rst
+   :language: rst
+   :lines: 87-91
+
+becomes:
+
+.. autosummary::
+   :toctree: generated/
+   :template: custom-template.rst
+
+   TestAccessor

sphinx_autosummary_accessors/__init__.py

@@ -3,23 +3,20 @@
 except ImportError:
     from importlib_metadata import version
 
-import pathlib
-
 from . import autosummary
 from .documenters import (
     AccessorAttributeDocumenter,
     AccessorCallableDocumenter,
     AccessorDocumenter,
     AccessorMethodDocumenter,
 )
+from .templates import templates_path  # noqa: F401
 
 try:
     __version__ = version("sphinx-autosummary-accessors")
 except Exception:
     __version__ = "999"
 
-templates_path = str(pathlib.Path(__file__).parent / "templates")
-
 
 def add_autosummary_create_documenter(func):
     import sphinx.ext.autosummary

sphinx_autosummary_accessors/autosummary.py

@@ -2,6 +2,8 @@
 
 from sphinx.ext.autosummary import Autosummary, generate
 
+from .templates import known_templates
+
 directives_re = re.compile(r"^\.\. ([^:]+):: (.+)$", re.MULTILINE)
 
 original_create_documenter = Autosummary.create_documenter
@@ -22,7 +24,7 @@ def create_documenter_from_template(autosummary, app, obj, parent, full_name):
 
     options = autosummary.options
     template_name = options.get("template", None)
-    if template_name is None:
+    if template_name is None or template_name not in known_templates:
         return original_create_documenter(autosummary, app, obj, parent, full_name)
 
     imported_members = options.get("imported_members", False)

sphinx_autosummary_accessors/templates.py

@@ -0,0 +1,6 @@
+import pathlib
+
+root = pathlib.Path(__file__).parent / "templates"
+
+known_templates = [str(path.relative_to(root)) for path in root.glob("**/*.rst")]
+templates_path = str(root)