feat: Release Insiders project

Author: pawamoy

README.md

@@ -11,3 +11,63 @@ Parse Sphinx-comments above attributes as docstrings.
 This project is available to sponsors only, through my Insiders program.
 See Insiders [explanation](https://mkdocstrings.github.io/griffe-sphinx/insiders/)
 and [installation instructions](https://mkdocstrings.github.io/griffe-sphinx/insiders/installation/).
+
+## Usage
+
+Griffe Sphinx allows reading Sphinx comments above attribute assignments as docstrings.
+
+```python
+# your_module.py
+
+#: Summary of your attribute.
+#:
+#: This is a longer description of your attribute.
+#: You can use any markup in here (Markdown, AsciiDoc, rST, etc.).
+#:
+#: Be careful with indented blocks: they need 4 spaces plus the initial 1-space indent, so 5.
+#:
+#:     print("hello!")
+your_attribute = "Hello Sphinx!"
+```
+
+This works for module attributes as well as class and instance attributes.
+
+```python
+class Hello:
+    #: Summary of attribute.
+    attr1 = "hello"
+
+    def __init__(self):
+        #: Summary of attribute.
+        self.attr2 = "sphinx"
+```
+
+Trailing comments (appearing at the end of a line) are not supported.
+
+You can now enable the extension when loading data with Griffe on the command-line, in Python code or with MkDocs.
+
+**On the command-line:**
+
+```bash
+griffe dump your_package -e griffe_sphinx
+```
+
+**In Python code:**
+
+```python
+import griffe
+
+data = griffe.load("your_package", extensions=griffe.load_extensions("griffe_sphinx"))
+```
+
+**With [MkDocs](https://www.mkdocs.org/):**
+
+```yaml
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          extensions:
+          - griffe_sphinx
+```

docs/insiders/goals.yml

@@ -7,7 +7,10 @@ goals:
     features: []
   1500:
     name: HyperLamp Navigation Tips
-    features: []
+    features:
+    - name: "[Project] Parse Sphinx-comments above attributes as docstrings"
+      ref: /
+      since: 2024/08/15
   2000:
     name: FusionDrive Ejection Configuration
     features: []

pyproject.toml

@@ -29,7 +29,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "griffe>=0.48",
+    "griffe>=0.49",
 ]
 
 [project.urls]

src/griffe_sphinx/_internals/extension.py

@@ -1,5 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
 import griffe
 
+logger = griffe.get_logger("griffe_sphinx")
+
 
 class SphinxCommentsExtension(griffe.Extension):
     """Parse Sphinx-comments above attributes as docstrings."""
+
+    def on_attribute_instance(
+        self,
+        *,
+        attr: griffe.Attribute,
+        agent: griffe.Visitor | griffe.Inspector,
+        **kwargs: Any,  # noqa: ARG002
+    ) -> None:
+        if attr.docstring is None:
+            if attr.lineno is None or attr.endlineno is None:
+                logger.debug(f"Skipping Sphinx-comments parsing for {attr.path}: lineno or endlineno is None")
+                return
+            if isinstance(attr.filepath, list):
+                # This should never happen (an attribute cannot be defined in a directory/native-namespace package),
+                # but for good measure we handle the case.
+                return
+            lineno = attr.lineno - 2
+            lines = []
+            while lineno and (line := attr.lines_collection[attr.filepath][lineno].lstrip()).startswith("#:"):
+                lines.append(line[3:])
+                lineno -= 1
+            if lines:
+                attr.docstring = griffe.Docstring(
+                    "\n".join(reversed(lines)),
+                    lineno=lineno + 2,
+                    endlineno=attr.lineno - 1,
+                    parent=attr,
+                    parser=agent.docstring_parser,
+                    parser_options=agent.docstring_options,
+                )

tests/test_extension.py

@@ -0,0 +1,36 @@
+"""Tests for the extension module."""
+
+from __future__ import annotations
+
+import griffe
+
+from griffe_sphinx import SphinxCommentsExtension
+
+
+def test_extension() -> None:
+    """Fetch comments from source."""
+    with griffe.temporary_visited_module(
+        """
+        #: Summary for `a`.
+        #:
+        #: Description for `a`.
+        a = 0
+
+        class C:
+            #: Summary for `b`.
+            #:
+            #: Description for `b`.
+            b = 1
+
+            def __init__(self):
+                #: Summary for `i`.
+                #:
+                #: Description for `i`.
+                self.i = 2
+
+        """,
+        extensions=griffe.load_extensions(SphinxCommentsExtension),
+    ) as module:
+        assert module["a"].docstring.value == "Summary for `a`.\n\nDescription for `a`."
+        assert module["C.b"].docstring.value == "Summary for `b`.\n\nDescription for `b`."
+        assert module["C.i"].docstring.value == "Summary for `i`.\n\nDescription for `i`."