pdoc 14.5.0__tar.gz → 14.6.0__tar.gz

{pdoc-14.5.0 → pdoc-14.6.0}/CHANGELOG.md

@@ -4,6 +4,28 @@
 
 ## Unreleased: pdoc next
 
+## 2024-07-24: pdoc 14.6.0
+
+- If `example.data.Data` is also exposed as `example.Data`, pdoc now links to `example.Data` in documentation.
+  ([#670](https://github.com/mitmproxy/pdoc/pull/670), @nathanthorpe, @mhils)
+- Add support for [GitHub Markdown Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
+  ([#718](https://github.com/mitmproxy/pdoc/pull/718), @mhils)
+- Improve rendering of enums on Python 3.12+.
+  ([#708](https://github.com/mitmproxy/pdoc/pull/708), @mhils)
+- Fix a bug where hyperlinks would get parsed as docstring references.
+  ([#709](https://github.com/mitmproxy/pdoc/pull/709), @mhils)
+- Fix a TypeError when trying to parse modules that implement `__dir__` incorrectly.
+  ([#710](https://github.com/mitmproxy/pdoc/pull/710), @mhils)
+- Fix a bug where a combination of `@dataclass` and `ctypes.Structure` would crash pdoc.
+  ([#711](https://github.com/mitmproxy/pdoc/pull/711), @mhils)
+- Update bundled version of markdown2.
+  ([#717](https://github.com/mitmproxy/pdoc/pull/717), @mhils)
+
+## 2024-06-25: pdoc 14.5.1
+
+- **[CVE-2024-38526](https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62):** Documentation generated with math mode (`pdoc --math`) does not include scripts
+  from polyfill.io anymore. Users who produce documentation with math mode should update immediately. All other users are unaffected.
+  ([#703](https://github.com/mitmproxy/pdoc/pull/703), @adhintz)
 
 ## 2024-05-16: pdoc 14.5.0
 

pdoc-14.6.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2024 Maximilian Hils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

{pdoc-14.5.0/pdoc.egg-info → pdoc-14.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.5.0
+Version: 14.6.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
-License: Unlicense
+License: MIT-0
 Project-URL: Homepage, https://pdoc.dev
 Project-URL: Source, https://github.com/mitmproxy/pdoc/
 Project-URL: Documentation, https://pdoc.dev/docs/pdoc.html

{pdoc-14.5.0 → pdoc-14.6.0}/pdoc/__init__.py

@@ -194,11 +194,17 @@ In general, we recommend keeping the following conventions:
 - If you want to document a special `__dunder__` method, the recommended way to do so is
   to not document the dunder method specifically, but to add some usage examples in the class documentation.
 
+> [!NOTE]
+> Hiding an item only removes it from documentation.
+> It is still displayed in the source code when clicking the "View Source" button.
+
 As a last resort, you can override pdoc's behavior with a custom module template (see
 [*How can I edit pdoc's HTML template?*](#edit-pdocs-html-template)).
 You can find an example at
 [`examples/custom-template/module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2).
 
+Hiding an item only removes it from documentation. It is still displayed in the source code when clicking the "View Source" button.
+
 ## ...exclude submodules from being documented?
 
 If you would like to exclude specific submodules from the documentation, the recommended way is to specify `__all__` as
@@ -475,7 +481,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__ = "14.5.0"  # this is read from setup.py
+__version__ = "14.6.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.5.0 → pdoc-14.6.0}/pdoc/__main__.py

@@ -265,12 +265,12 @@ def get_dev_version() -> str:
 
 def _nicer_showwarning(message, category, filename, lineno, file=None, line=None):
     """A replacement for `warnings.showwarning` that renders warnings in a more visually pleasing way."""
-    if category == UserWarning:
+    if category is UserWarning:
         print(
             f"{yellow}Warn:{default} {message} {gray}({filename}:{lineno}){default}",
             file=sys.stderr,
         )
-    elif category == RuntimeWarning:
+    elif category is RuntimeWarning:
         print(
             f"{yellow}Warn:{default} {message}",
             file=sys.stderr,

{pdoc-14.5.0 → pdoc-14.6.0}/pdoc/doc.py

@@ -587,15 +587,21 @@ class Class(Namespace[type]):
         if doc == dict.__doc__:
             # Don't display default docstring for dict subclasses (primarily TypedDict).
             return ""
-        is_dataclass_with_default_docstring = (
-            dataclasses.is_dataclass(self.obj)
-            # from https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py
-            and doc
-            == self.obj.__name__
-            + str(inspect.signature(self.obj)).replace(" -> None", "")
-        )
-        if is_dataclass_with_default_docstring:
+        if doc in _Enum_default_docstrings:
+            # Don't display default docstring for enum subclasses.
             return ""
+        if dataclasses.is_dataclass(self.obj) and doc.startswith(self.obj.__name__):
+            try:
+                sig = inspect.signature(self.obj)
+            except Exception:
+                pass
+            else:
+                # from https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py
+                is_dataclass_with_default_docstring = doc == self.obj.__name__ + str(
+                    sig
+                ).replace(" -> None", "")
+                if is_dataclass_with_default_docstring:
+                    return ""
         return doc
 
     @cached_property
@@ -1306,6 +1312,15 @@ def _safe_getdoc(obj: Any) -> str:
         return doc.strip()
 
 
+_Enum_default_docstrings = tuple(
+    {
+        _safe_getdoc(enum.Enum),
+        _safe_getdoc(enum.IntEnum),
+        _safe_getdoc(_safe_getattr(enum, "StrEnum", enum.Enum)),
+    }
+)
+
+
 def _remove_memory_addresses(x: str) -> str:
     """Remove memory addresses from repr() output"""
     return re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", x)

{pdoc-14.5.0 → pdoc-14.6.0}/pdoc/docstrings.py

@@ -427,7 +427,7 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
             else:
                 heading = ""
             return (
-                f'{ind}<div class="pdoc-alert pdoc-alert-{type}" markdown="1">\n'
+                f'{ind}<div class="alert {type}" markdown="1">\n'
                 f"{heading}"
                 f"{indent(contents, ind)}\n"
                 f"{ind}</div>\n"

{pdoc-14.5.0 → pdoc-14.6.0}/pdoc/extract.py

@@ -253,7 +253,7 @@ def iter_modules2(module: types.ModuleType) -> dict[str, pkgutil.ModuleInfo]:
     # This is a hacky workaround to register them.
     members = dir(module) if mod_all is None else mod_all
     for name in members:
-        if name in submodules or name == "__main__":
+        if name in submodules or name == "__main__" or not isinstance(name, str):
             continue
         member = getattr(module, name, None)
         is_wild_child_module = (