hippogriffe 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

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
@@ -230,18 +235,6 @@ def _get_repo_url(repo_url: None | str) -> tuple[pathlib.Path, str]:
             "`hippogriffe.show_source_links` requires specifying a top-level "
             "`repo_url`."
         )
-    is_github = (
-        repo_url.removeprefix("https://")
-        .removeprefix("https://")
-        .startswith("github.com")
-    )
-    if not is_github:
-        # We need to format the `repo_url` to what the repo expects, so we have to
-        # hardcode this in.
-        raise ValueError(
-            "`hippogriffe.show_source_links` currently only supports "
-            "`repo_url: https://github.com/...`."
-        )
     try:
         git_head = subprocess.run(
             ["git", "rev-parse", "HEAD"], capture_output=True, check=False
@@ -259,9 +252,19 @@ def _get_repo_url(repo_url: None | str) -> tuple[pathlib.Path, str]:
     else:
         toplevel = pathlib.Path(git_toplevel.stdout.decode().strip())
         commit_hash = git_head.stdout.decode().strip()
-    repo_url = (
-        f"{repo_url.removesuffix('/')}/blob/{commit_hash}/{{path}}#L{{start}}-{{end}}"
-    )
+    raw_url = repo_url.removeprefix("https://").removeprefix("https://")
+    if raw_url.startswith("github.com") or raw_url.startswith("gitlab.com"):
+        repo_url = (
+            f"{repo_url.removesuffix('/')}/blob/{commit_hash}/{{path}}"
+            "#L{start}-{end}"
+        )
+    else:
+        # We need to format the `repo_url` to what the repo expects, so we have to
+        # hardcode this in.
+        raise ValueError(
+            "`hippogriffe.show_source_links` currently only supports "
+            "`repo_url: https://github.com/...` and `repo_url: https://gitlab.com/...`."
+        )
     return toplevel, repo_url
 
 
@@ -283,7 +286,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/_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.dist-info → hippogriffe-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hippogriffe
-Version: 0.1.0
+Version: 0.1.2
 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.dist-info → hippogriffe-0.1.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
 hippogriffe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hippogriffe/_extension.py,sha256=hkcHakdZO2l4IWfmz6gXY4lNItj8pVlJjlLAIoz9TMA,12970
-hippogriffe/_plugin.py,sha256=OQ6B_iWSur3yiYr5rxTpGahFtWzuRLqCQVndWoegFcY,4459
+hippogriffe/_extension.py,sha256=zg3Q5h5ziLOX46BXYOpwrXQ7EFGJP7UwKXjKMh7GYjY,14014
+hippogriffe/_plugin.py,sha256=H0oPka_7URED9wOVYAWUNTWTJXFmH6q7g2W2G5hy64c,4564
 hippogriffe/assets/_hippogriffe.css,sha256=BgyZLCaOaZNgQErdUb01vpNso4ilUMmoZ5d_OeVpfRE,147
 hippogriffe/templates/material/hippogriffe/class.html.jinja,sha256=5i624gIuZfnf5toH3jWclzg1qlekqIZ2ODbpzeZcULw,954
 hippogriffe/templates/material/hippogriffe/fn.html.jinja,sha256=vxrWOPkPkGD3Po9hbcYlyEjsJKhJmOHic4G5t2J0djc,196
 hippogriffe/templates/material/hippogriffe/hippogriffe.jinja,sha256=KxTBKY0XqiFzqTT1iqFxhN2GhmtwLT4GWc8S86zyjOc,583
-hippogriffe-0.1.0.dist-info/METADATA,sha256=VON3g_gsdXPZ1g1A_hxcCs8i7g5aqPFSSULd5T9kx0A,15988
-hippogriffe-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hippogriffe-0.1.0.dist-info/entry_points.txt,sha256=Et3dFNWG-biZ7XCvPI9na-buFT_hht1YT0p0JDNEQQM,158
-hippogriffe-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hippogriffe-0.1.0.dist-info/RECORD,,
+hippogriffe-0.1.2.dist-info/METADATA,sha256=IiWbdutZDQd0mrtyQyES29rTdHJEyrZmK7I0jQL0UJ0,16274
+hippogriffe-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hippogriffe-0.1.2.dist-info/entry_points.txt,sha256=Et3dFNWG-biZ7XCvPI9na-buFT_hht1YT0p0JDNEQQM,158
+hippogriffe-0.1.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hippogriffe-0.1.2.dist-info/RECORD,,