pdoc 13.0.1__tar.gz → 13.1.1__tar.gz

{pdoc-13.0.1 → pdoc-13.1.1}/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+
+## 2023-04-24: pdoc 13.1.1
+
+ - Fix rendering of dynamically modified docstrings.
+   ([#537](https://github.com/mitmproxy/pdoc/pull/537), @mhils)
+ - Updated bundled markdown2 version to fix a bug with empty code blocks.
+   ([#537](https://github.com/mitmproxy/pdoc/pull/537), @mhils)
+ - `pdoc.doc_ast.AstInfo` now has separate `func_docstrings` and `var_docstrings` attributes 
+   instead of one combined one.
+   ([#537](https://github.com/mitmproxy/pdoc/pull/537), @mhils)
+
+## 2023-03-31: pdoc 13.1.0
+
+ - Add support for rendering [Mermaid diagrams](https://mermaid.js.org/) by passing `--mermaid`.
+   ([#525](https://github.com/mitmproxy/pdoc/pull/525), @thearchitector, @mhils)
+ - Add rudimentary support for `typing_extensions.Literal` on Python 3.7.
+   ([#527](https://github.com/mitmproxy/pdoc/pull/527), @mhils)
+
+## 2023-03-21: pdoc 13.0.1
+
  - Add additional Jinja2 blocks to allow a more fine-grained customization of the menu.
    ([#521](https://github.com/mitmproxy/pdoc/pull/521), @mikkelakromann)
  - Fix a crash in pdoc 13.0.0 when `__init__.py` is passed as a file to pdoc.

{pdoc-13.0.1/pdoc.egg-info → pdoc-13.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 13.0.1
+Version: 13.1.1
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense

{pdoc-13.0.1 → pdoc-13.1.1}/pdoc/__init__.py

@@ -257,6 +257,12 @@ Run `pdoc --math`, and pdoc will render formulas in your docstrings. See
 [`math_demo`](https://pdoc.dev/docs/math/math_demo.html) for details.
 
 
+## ...render Mermaid diagrams?
+
+Run `pdoc --mermaid`, and pdoc will render mermaid diagrams in your docstrings. See
+[`mermaid_demo`](https://pdoc.dev/docs/mermaid/mermaid_demo.html) for details.
+
+
 ## ...add my project's logo?
 
 See [*Customizing pdoc*](#customizing-pdoc).
@@ -418,6 +424,7 @@ In addition, the following extra syntax elements are enabled:
   - **[markdown-in-html][]:** Allow the use of `markdown="1"` in a
     block HTML tag to have markdown processing be done on its contents.
     Similar to [PHP-Markdown Extra][] but with some limitations.
+  - **[mermaid][]:** Allows rendering Mermaid diagrams from included Markdown files using <code>```mermaid</code> fence blocks.
   - **[pyshell][]:** Treats unindented Python interactive shell
     sessions as `<code>` blocks.
   - **strike:** Parse `~~strikethrough~~` formatting.
@@ -434,6 +441,7 @@ In addition, the following extra syntax elements are enabled:
 [footnotes]: https://github.com/trentm/python-markdown2/wiki/footnotes
 [header-ids]: https://github.com/trentm/python-markdown2/wiki/header-ids
 [markdown-in-html]: https://github.com/trentm/python-markdown2/wiki/markdown-in-html
+[mermaid]: https://github.com/trentm/python-markdown2/wiki/mermaid
 [pyshell]: https://github.com/trentm/python-markdown2/wiki/pyshell
 [tables]: https://github.com/trentm/python-markdown2/wiki/tables
 [GitHub-Flavored Markdown]: https://github.github.com/gfm/
@@ -453,7 +461,7 @@ You can find an example in [`examples/library-usage`](https://github.com/mitmpro
 from __future__ import annotations
 
 __docformat__ = "markdown"  # explicitly disable rST processing in the examples above.
-__version__ = "13.0.1"  # this is read from setup.py
+__version__ = "13.1.1"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-13.0.1 → pdoc-13.1.1}/pdoc/__main__.py

@@ -96,6 +96,12 @@ renderopts.add_argument(
     default=False,
     help="Include MathJax from a CDN to enable math formula rendering.",
 )
+renderopts.add_argument(
+    "--mermaid",
+    action=BooleanOptionalAction,
+    default=False,
+    help="Include Mermaid.js from a CDN to enable Mermaid diagram rendering.",
+)
 renderopts.add_argument(
     "--search",
     action=BooleanOptionalAction,
@@ -176,6 +182,7 @@ def cli(args: list[str] | None = None) -> None:
         logo=opts.logo,
         logo_link=opts.logo_link,
         math=opts.math,
+        mermaid=opts.mermaid,
         search=opts.search,
         show_source=opts.show_source,
         template_directory=opts.template_directory,

{pdoc-13.0.1 → pdoc-13.1.1}/pdoc/_compat.py

@@ -109,8 +109,11 @@ else:  # pragma: no cover
 
     # There is no Literal on 3.7, so we just make one up. It should not be used anyways!
 
-    class Literal:
-        pass
+    try:
+        from typing_extensions import Literal
+    except ImportError:
+        class Literal:
+            pass
 
     # get_origin is adapted from
     # https://github.com/python/cpython/blob/863eb7170b3017399fb2b786a1e3feb6457e54c2/Lib/typing.py#L1474-L1515

{pdoc-13.0.1 → pdoc-13.1.1}/pdoc/doc.py

@@ -223,6 +223,11 @@ class Namespace(Doc[T], metaclass=ABCMeta):
     def _var_docstrings(self) -> dict[str, str]:
         """A mapping from some member variable names to their docstrings."""
 
+    @cached_property
+    @abstractmethod
+    def _func_docstrings(self) -> dict[str, str]:
+        """A mapping from some member function names to their raw (not processed by any @decorators) docstrings."""
+
     @cached_property
     @abstractmethod
     def _var_annotations(self) -> dict[str, Any]:
@@ -312,6 +317,8 @@ class Namespace(Doc[T], metaclass=ABCMeta):
                 )
             if self._var_docstrings.get(name):
                 doc.docstring = self._var_docstrings[name]
+            if self._func_docstrings.get(name) and not doc.docstring:
+                doc.docstring = self._func_docstrings[name]
             members[doc.name] = doc
 
         if isinstance(self, Module):
@@ -409,7 +416,11 @@ class Module(Namespace[types.ModuleType]):
 
     @cached_property
     def _var_docstrings(self) -> dict[str, str]:
-        return doc_ast.walk_tree(self.obj).docstrings
+        return doc_ast.walk_tree(self.obj).var_docstrings
+
+    @cached_property
+    def _func_docstrings(self) -> dict[str, str]:
+        return doc_ast.walk_tree(self.obj).func_docstrings
 
     @cached_property
     def _var_annotations(self) -> dict[str, Any]:
@@ -478,7 +489,11 @@ class Module(Namespace[types.ModuleType]):
 
     @cached_property
     def _documented_members(self) -> set[str]:
-        return self._var_docstrings.keys() | self._var_annotations.keys()
+        return (
+            self._var_docstrings.keys()
+            | self._func_docstrings.keys()
+            | self._var_annotations.keys()
+        )
 
     @cached_property
     def _member_objects(self) -> dict[str, Any]:
@@ -526,6 +541,8 @@ class Module(Namespace[types.ModuleType]):
                     members[name] = obj
             for name in self._var_docstrings:
                 members.setdefault(name, empty)
+            for name in self._func_docstrings:
+                members.setdefault(name, empty)
 
             members, notfound = doc_ast.sort_by_source(self.obj, {}, members)
             members.update(notfound)
@@ -587,7 +604,15 @@ class Class(Namespace[type]):
     def _var_docstrings(self) -> dict[str, str]:
         docstrings: dict[str, str] = {}
         for cls in self._mro:
-            for name, docstr in doc_ast.walk_tree(cls).docstrings.items():
+            for name, docstr in doc_ast.walk_tree(cls).var_docstrings.items():
+                docstrings.setdefault(name, docstr)
+        return docstrings
+
+    @cached_property
+    def _func_docstrings(self) -> dict[str, str]:
+        docstrings: dict[str, str] = {}
+        for cls in self._mro:
+            for name, docstr in doc_ast.walk_tree(cls).func_docstrings.items():
                 docstrings.setdefault(name, docstr)
         return docstrings
 
@@ -642,7 +667,11 @@ class Class(Namespace[type]):
         decls: dict[str, tuple[str, str]] = {}
         for cls in self._mro:
             treeinfo = doc_ast.walk_tree(cls)
-            for name in treeinfo.docstrings.keys() | treeinfo.annotations.keys():
+            for name in (
+                treeinfo.var_docstrings.keys()
+                | treeinfo.func_docstrings.keys()
+                | treeinfo.annotations.keys()
+            ):
                 decls.setdefault(name, (cls.__module__, f"{cls.__qualname__}.{name}"))
             for name in cls.__dict__:
                 decls.setdefault(name, (cls.__module__, f"{cls.__qualname__}.{name}"))

{pdoc-13.0.1 → pdoc-13.1.1}/pdoc/doc_ast.py

@@ -85,8 +85,10 @@ def unparse(tree: ast.AST):
 class AstInfo:
     """The information extracted from walking the syntax tree."""
 
-    docstrings: dict[str, str]
+    var_docstrings: dict[str, str]
     """A qualname -> docstring mapping."""
+    func_docstrings: dict[str, str]
+    """A qualname -> docstring mapping for functions."""
     annotations: dict[str, str]
     """A qualname -> annotation mapping.
     
@@ -104,7 +106,8 @@ def walk_tree(obj: types.ModuleType | type) -> AstInfo:
 def _walk_tree(
     tree: ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
 ) -> AstInfo:
-    docstrings = {}
+    var_docstrings = {}
+    func_docstrings = {}
     annotations = {}
     for a, b in _pairwise_longest(_nodes(tree)):
         if isinstance(a, ast.AnnAssign) and isinstance(a.target, ast.Name) and a.simple:
@@ -122,7 +125,7 @@ def _walk_tree(
         elif isinstance(a, ast.FunctionDef) and a.body:
             first = a.body[0]
             if isinstance(first, ast.Expr) and isinstance(first.value, ast.Str):
-                docstrings[a.name] = inspect.cleandoc(first.value.s).strip()
+                func_docstrings[a.name] = inspect.cleandoc(first.value.s).strip()
             continue
         else:
             continue
@@ -131,14 +134,15 @@ def _walk_tree(
             and isinstance(b.value, ast.Constant)
             and isinstance(b.value.value, str)
         ):
-            docstrings[name] = inspect.cleandoc(b.value.value).strip()
+            var_docstrings[name] = inspect.cleandoc(b.value.value).strip()
         elif isinstance(b, ast.Expr) and isinstance(
             b.value, ast.Str
         ):  # pragma: no cover
             # Python <= 3.7
-            docstrings[name] = inspect.cleandoc(b.value.s).strip()
+            var_docstrings[name] = inspect.cleandoc(b.value.s).strip()
     return AstInfo(
-        docstrings,
+        var_docstrings,
+        func_docstrings,
         annotations,
     )