hippogriffe 0.1.0__tar.gz → 0.1.1__tar.gz

{hippogriffe-0.1.0 → hippogriffe-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hippogriffe
-Version: 0.1.0
+Version: 0.1.1
 Summary: A simple ipynb->md converter for MkDocs
 Project-URL: repository, https://github.com/patrick-kidger/hippogriffe
 Author-email: Patrick Kidger <contact@kidger.site>
@@ -229,6 +229,8 @@ This is a set of tweaks on top of the MkDocs + `mkdocstrings[python]` + `griffe`
     - Fixes unions/generics/etc. to display as e.g. `int | str` rather than just `Union`, or `tuple[int, str]` rather than just `tuple`.
     - Respects your public API: if a type is declared in your documentation as `::: yourlib.Foo` then its usage in type annotations will match: `some_fn(foo: yourlib.Foo)`.
 - Show base classes inline after the class.
+- Drops the `-> None` return annotation from `__init__` methods.
+- Attributes display as `[attr] somelib.someattr` instead of `[attr] somelib.someattr = some_value [module]`. (I don't find usually-long default values to be useful documentation, nor the 'module' tag to be informative.)
 
 Before                 | After
 :---------------------:|:----------------------:

{hippogriffe-0.1.0 → hippogriffe-0.1.1}/README.md

@@ -7,6 +7,8 @@ This is a set of tweaks on top of the MkDocs + `mkdocstrings[python]` + `griffe`
     - Fixes unions/generics/etc. to display as e.g. `int | str` rather than just `Union`, or `tuple[int, str]` rather than just `tuple`.
     - Respects your public API: if a type is declared in your documentation as `::: yourlib.Foo` then its usage in type annotations will match: `some_fn(foo: yourlib.Foo)`.
 - Show base classes inline after the class.
+- Drops the `-> None` return annotation from `__init__` methods.
+- Attributes display as `[attr] somelib.someattr` instead of `[attr] somelib.someattr = some_value [module]`. (I don't find usually-long default values to be useful documentation, nor the 'module' tag to be informative.)
 
 Before                 | After
 :---------------------:|:----------------------:

{hippogriffe-0.1.0 → hippogriffe-0.1.1}/hippogriffe/_extension.py

@@ -23,6 +23,10 @@ def get_templates_path():
     return _here / "templates"
 
 
+class _NotInPublicApiException(Exception):
+    pass
+
+
 class _PublicApi:
     def __init__(
         self,
@@ -100,7 +104,8 @@ class _PublicApi:
             for m in self._public_modules:
                 if key.startswith(m + "."):
                     return key, False
-            raise Exception(
+            # Not using `KeyError` because that displays its message with `repr`.
+            raise _NotInPublicApiException(
                 f"Tried and failed to find {key} in the public API. Commons reasons "
                 "for this error are:\n"
                 "- If it is from outside this package, then that package is not listed "
@@ -216,7 +221,7 @@ def _collect_bases(
         elif isinstance(base, griffe.Class):
             try:
                 base, autoref = public_api[base.path]
-            except KeyError:
+            except _NotInPublicApiException:
                 bases.update(_collect_bases(base, public_api, public_modules))
             else:
                 bases[base] = autoref
@@ -283,7 +288,31 @@ class HippogriffeExtension(griffe.Extension):
     ) -> None:
         del agent, kwargs
         assert not isinstance(node, ast.AST)
-        func.extra["hippogriffe"]["signature"] = inspect.signature(node.obj)
+        signature = inspect.signature(node.obj)
+        try:
+            name = node.obj.__name__
+        except AttributeError:
+            pass
+        else:
+            if name == "__init__":
+                signature = signature.replace(return_annotation=inspect.Signature.empty)
+        func.extra["hippogriffe"]["signature"] = signature
+
+    def on_attribute_instance(
+        self,
+        *,
+        node: ast.AST | griffe.ObjectNode,
+        attr: griffe.Attribute,
+        agent: griffe.Visitor | griffe.Inspector,
+        **kwargs: Any,
+    ) -> None:
+        del node, agent, kwargs
+        # Knowing the value is IMO usually not useful. That is what documentation
+        # directly is for.
+        attr.value = None
+        # This is used to indicate that it is a module attribute, but IMO that's not
+        # super clear in the docs.
+        attr.labels.discard("module")
 
     def on_package_loaded(
         self, *, pkg: griffe.Module, loader: griffe.GriffeLoader, **kwargs: Any

{hippogriffe-0.1.0 → hippogriffe-0.1.1}/hippogriffe/_plugin.py

@@ -12,6 +12,10 @@ from mkdocstrings import AutoDocProcessor
 
 
 _here = pathlib.Path(__file__).resolve().parent
+_regex = re.compile(
+    r"^\s*" + AutoDocProcessor.regex.pattern.removeprefix("^"),
+    AutoDocProcessor.regex.flags,
+)
 
 
 class PluginConfig(Config):
@@ -102,7 +106,7 @@ class HippogriffePlugin(BasePlugin[PluginConfig]):
         top_level_public_api.remove("")
         for file in files:
             if file.is_documentation_page():
-                for match in AutoDocProcessor.regex.finditer(file.content_string):
+                for match in _regex.finditer(file.content_string):
                     top_level_public_api.add(match["name"])
         files.append(
             File.generated(

{hippogriffe-0.1.0 → hippogriffe-0.1.1}/pyproject.toml

@@ -25,7 +25,7 @@ name = "hippogriffe"
 readme = "README.md"
 requires-python = ">=3.10"
 urls = {repository = "https://github.com/patrick-kidger/hippogriffe"}
-version = "0.1.0"
+version = "0.1.1"
 
 [project.optional-dependencies]
 dev = ["pre-commit"]