Initial commit

Author: znichollscr

README.md

@@ -0,0 +1,68 @@
+# mkdocstrings-python-accessors
+
+Python handler for [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings)
+supporting documentation of accessors.
+Takes inspiration from [sphinx-autosummary-accessors](https://github.com/xarray-contrib/sphinx-autosummary-accessors).
+
+This package extends [mkdocstrings-python](https://github.com/mkdocstrings/python)
+(well, technically, [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref))
+to support more desirable documentation of accessors.
+
+The accessors pattern is normally something like the following.
+Let's take [`pandas`](https://pandas.pydata.org/docs/development/extending.html#registering-custom-accessors).
+It is possible to register custom accessors, so you can do operations via that namespace.
+For example, `pd.DataFrame.custom_namespace.operation()`.
+When implemented, this is usually done via some sub-class,
+which is then registered with the upstream package (in this case pandas).
+The pattern normally looks something like the below
+
+```python
+@pd.register_accessor("custom_namespace")
+class CustomNamespaceAccessor:
+    def __init__(self, pandas_obj):
+        self._obj = pandas_obj
+
+    def operation(self):
+        # Normally you do a more elaborate operation than this,
+        # but you get the idea.
+        return self._obj * 2
+```
+
+When you come to document this,
+you normally get just the documentation for the class `CustomNamespaceAccessor`.
+For example, if you include the following in your docs.
+
+```md
+::: CustomNamespaceAccessor
+    handler: python
+```
+
+Then you will get documentation for `CustomNamespaceAccessor`.
+
+This package introduces the following options.
+
+```md
+::: CustomNamespaceAccessor
+    handler: python_accessors
+    options:
+        namespace: "pd.DataFrame.custom_namespace"
+```
+
+With this, the documentation will be transformed.
+Instead of creating docs for `CustomNamespaceAccessor`,
+you will instead get docs for `pd.DataFrame.custom_namespace`.
+
+The configuration we have found works best is the below,
+but you can use all the normal options that can be passed to
+[mkdocstrings-python](https://github.com/mkdocstrings/python)
+and [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref)
+to modify the appearance as you wish.
+
+```md
+::: CustomNamespaceAccessor
+    handler: python_accessors
+    options:
+        namespace: "pd.DataFrame.custom_namespace"
+        show_root_full_path: false
+        show_root_heading: true
+```

pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "mkdocstrings-python-accessors"
+version = "0.3.4a1"
+description = "A Python accessor handler for mkdocstrings."
+authors = [{name = "Zebedee Nicholls", email = "zebedee.nicholls@climate-resource.com"}]
+license = {text = "BSD-3-Clause"}
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = []
+classifiers = [
+    # TODO: pull some of these across into our copier template
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mkdocstrings-python-xref>=1.0",
+]
+
+# TODO: pull into our copier template
+[project.urls]
+Homepage = "https://climate-resource.github.io/mkdocstrings-python-accessors"
+Documentation = "https://climate-resource.github.io/mkdocstrings-python-accessors"
+Changelog = "https://climate-resource.github.io/mkdocstrings-python-accessors/changelog"
+Repository = "https://github.com/climate-resource/mkdocstrings-python-accessors"
+Issues = "https://github.com/climate-resource/mkdocstrings-python-accessors/issues"
+Discussions = "https://github.com/climate-resource/mkdocstrings-python-accessors/discussions"
+
+[build-system]
+requires = ["pdm-backend"]
+build-backend = "pdm.backend"
+
+[tool.pdm.build]
+package-dir = "src"
+includes = ["src/mkdocstrings_handlers"]
+# Consider adding something like this to our copier template.
+# Include as much as possible in the source distribution, to help redistributors.
+excludes = ["**/.pytest_cache"]
+source-includes = [
+    # "docs",
+    # "scripts",
+    # "tests",
+    # "mkdocs.yml",
+    # "*.md",
+    "LICENCE",
+]

src/mkdocstrings_handlers/python_accessors/__init__.py

@@ -0,0 +1,7 @@
+"""Python handler for documenting accessors with mkdocstrings"""
+
+from .handler import PythonAccessorsHandler
+
+__all__ = ["get_handler"]
+
+get_handler = PythonAccessorsHandler

src/mkdocstrings_handlers/python_accessors/handler.py

@@ -0,0 +1,70 @@
+"""
+Implementation of python_accessors handler
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import griffe
+from mkdocstrings.loggers import get_logger
+from mkdocstrings_handlers.python_xref.handler import PythonRelXRefHandler
+
+__all__ = ["PythonAccessorsHandler"]
+
+logger = get_logger(__name__)
+
+
+class PythonAccessorsHandler(PythonRelXRefHandler):
+    """
+    Extended version of mkdocstrings PythonRelXRefHandler handler
+
+    Converts accessors into the namespace of the user's choosing.
+
+    Could also be done with the standard Python handler I expect,
+    but that's not what the project I'm working on needs.
+    """
+
+    def render(self, data: griffe.Object, config: Mapping[str, Any]) -> str:
+        """
+        Render the docs
+
+        Parameters
+        ----------
+        data
+            Data to render
+
+        config
+            Configuration
+
+        Returns
+        -------
+        :
+            Rendered docs
+        """
+        if not isinstance(data, griffe.Class):
+            raise NotImplementedError(data)
+
+        try:
+            namespace = config["namespace"]
+        except KeyError:
+            msg = f"Please specify the namespace to use with {data.name}. {data.path=}"
+            raise KeyError(msg)
+
+        # Set overall name
+        data.name = namespace
+
+        # Then update names for individual members
+        member_keys = list(data.members.keys())
+        for name in member_keys:
+            if name.startswith("_"):
+                # Don't document hidden methods etc.
+                # Could make this configuration instead
+                # if real customisation was needed.
+                data.del_member(name)
+                continue
+
+            data.members[name].name = f"{namespace}.{name}"
+
+        return super().render(data, config)