pdoc 14.4.0__tar.gz → 14.5.1__tar.gz

{pdoc-14.4.0 → pdoc-14.5.1}/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 ## Unreleased: pdoc next
 
+- **Security:** Documentation generated with math mode (`pdoc --math`) does not include scripts
+  from polyfill.io anymore. See https://sansec.io/research/polyfill-supply-chain-attack for details.
+  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
+
+- The `.. include:` rST directive now supports start-line, end-line, start-after, end-before options.
+  ([#684](https://github.com/mitmproxy/pdoc/pull/684), @frankharkins)
+- Fix image embedding in included rST files.
+  ([#692](https://github.com/mitmproxy/pdoc/pull/692), @meghprkh)
+- Support type-hints from stub-only packages. E.g: `scipy-stubs`
+  ([#671](https://github.com/mitmproxy/pdoc/pull/671), @erikdesmedt)
+- Modify css styles for MathJax to remove unnessesary scroll bars
+  ([#675](https://github.com/mitmproxy/pdoc/pull/675), @thehappycheese)
 
 ## 2024-01-18: pdoc 14.4.0
 

{pdoc-14.4.0/pdoc.egg-info → pdoc-14.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.4.0
+Version: 14.5.1
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -24,8 +24,22 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 License-File: LICENSE
+Requires-Dist: Jinja2>=2.11.0
+Requires-Dist: pygments>=2.12.0
+Requires-Dist: MarkupSafe
+Requires-Dist: astunparse; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-pygments; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pygments>=2.14.0; extra == "dev"
+Requires-Dist: pdoc-pyo3-sample-library==1.0.11; extra == "dev"
 
 <p align="center">
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
@@ -95,10 +109,6 @@ As an open source project, pdoc welcomes contributions of all forms.
 
 [![Dev Guide](https://shields.mitmproxy.org/badge/dev_docs-CONTRIBUTING.md-blue)](https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md)
 
-Also, please feel free to join our developer Slack!
-
-[![Slack Developer Chat](https://shields.mitmproxy.org/badge/slack-mitmproxy-E01563.svg)](http://slack.mitmproxy.org/)
-
 
 ## pdoc vs. pdoc3
 

{pdoc-14.4.0 → pdoc-14.5.1}/README.md

@@ -66,10 +66,6 @@ As an open source project, pdoc welcomes contributions of all forms.
 
 [![Dev Guide](https://shields.mitmproxy.org/badge/dev_docs-CONTRIBUTING.md-blue)](https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md)
 
-Also, please feel free to join our developer Slack!
-
-[![Slack Developer Chat](https://shields.mitmproxy.org/badge/slack-mitmproxy-E01563.svg)](http://slack.mitmproxy.org/)
-
 
 ## pdoc vs. pdoc3
 

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/__init__.py

@@ -283,7 +283,16 @@ You can include external Markdown files in your documentation by using reStructu
 """
 ```
 
-Since version 11, pdoc processes such reStructuredText elements by default.
+You can also include only parts of a file with the
+[`start-line`, `end-line`, `start-after`, and `end-after` options](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment):
+
+```python
+"""
+.. include:: ../README.md
+   :start-line: 1
+   :end-before: Changelog
+"""
+```
 
 
 ## ...add a title page?
@@ -462,10 +471,11 @@ to your Python code before pdoc is used.
 It is also possible to create `pdoc.doc.Module` objects directly and modify them before rendering.
 You can find an example in [`examples/library-usage`](https://github.com/mitmproxy/pdoc/tree/main/examples/library-usage).
 '''
+
 from __future__ import annotations
 
 __docformat__ = "markdown"  # explicitly disable rST processing in the examples above.
-__version__ = "14.4.0"  # this is read from setup.py
+__version__ = "14.5.1"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/doc.py

@@ -15,6 +15,7 @@ All documentation types make heavy use of `@functools.cached_property` decorator
 This means they have a large set of attributes that are lazily computed on first access.
 By convention, all attributes are read-only, although this is not enforced at runtime.
 """
+
 from __future__ import annotations
 
 from abc import ABCMeta
@@ -1030,7 +1031,9 @@ class Variable(Doc[None]):
 
     kind = "variable"
 
-    default_value: Any | empty  # technically Any includes empty, but this conveys intent.
+    default_value: (
+        Any | empty
+    )  # technically Any includes empty, but this conveys intent.
     """
     The variable's default value.
     

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/doc_ast.py

@@ -3,6 +3,7 @@ This module handles all interpretation of the *Abstract Syntax Tree (AST)* in pd
 
 Parsing the AST is done to extract docstrings, type annotations, and variable declarations from `__init__`.
 """
+
 from __future__ import annotations
 
 import ast
@@ -51,18 +52,15 @@ def _get_source(obj: Any) -> str:
 
 
 @overload
-def parse(obj: types.ModuleType) -> ast.Module:
-    ...
+def parse(obj: types.ModuleType) -> ast.Module: ...
 
 
 @overload
-def parse(obj: types.FunctionType) -> ast.FunctionDef | ast.AsyncFunctionDef:
-    ...
+def parse(obj: types.FunctionType) -> ast.FunctionDef | ast.AsyncFunctionDef: ...
 
 
 @overload
-def parse(obj: type) -> ast.ClassDef:
-    ...
+def parse(obj: type) -> ast.ClassDef: ...
 
 
 def parse(obj):

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/doc_pyi.py

@@ -3,6 +3,7 @@ This module is responsible for patching `pdoc.doc.Doc` objects with type annotat
 in `.pyi` type stub files ([PEP 561](https://peps.python.org/pep-0561/)).
 This makes it possible to add type hints for native modules such as modules written using [PyO3](https://pyo3.rs/).
 """
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -25,10 +26,17 @@ def find_stub_file(module_name: str) -> Path | None:
     """Try to find a .pyi file with type stubs for the given module name."""
     module_path = module_name.replace(".", "/")
 
-    for dir in sys.path:
+    # Find .pyi-file in a PEP 0561 compatible stub-package
+    module_part_name = module_name.split(".")
+    module_part_name[0] = f"{module_part_name[0]}-stubs"
+    module_stub_path = "/".join(module_part_name)
+
+    for search_dir in sys.path:
         file_candidates = [
-            Path(dir) / (module_path + ".pyi"),
-            Path(dir) / (module_path + "/__init__.pyi"),
+            Path(search_dir) / (module_path + ".pyi"),
+            Path(search_dir) / (module_path + "/__init__.pyi"),
+            Path(search_dir) / (module_stub_path + ".pyi"),
+            Path(search_dir) / (module_stub_path + "/__init__.pyi"),
         ]
         for f in file_candidates:
             if f.exists():

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/doc_types.py

@@ -5,6 +5,7 @@ In particular, it provides functionality to resolve
 [typing.ForwardRef](https://docs.python.org/3/library/typing.html#typing.ForwardRef) objects without raising an
 exception.
 """
+
 from __future__ import annotations
 
 import functools

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/docstrings.py

@@ -10,6 +10,7 @@ If you miss a particular feature for your favorite flavor, contributions are wel
 That being said, please keep the complexity low and make sure that changes are
 accompanied by matching snapshot tests in `test/testdata/`.
 """
+
 from __future__ import annotations
 
 import base64
@@ -359,6 +360,38 @@ def _rst_links(contents: str) -> str:
     return contents
 
 
+def _rst_extract_options(contents: str) -> tuple[str, dict[str, str]]:
+    """
+    Extract options from the beginning of reStructuredText directives.
+
+    Return the trimmed content and a dict of options.
+    """
+    options = {}
+    while match := re.match(r"^\s*:(.+?):(.*)([\s\S]*)", contents):
+        key, value, contents = match.groups()
+        options[key] = value.strip()
+
+    return contents, options
+
+
+def _rst_include_trim(contents: str, options: dict[str, str]) -> str:
+    """
+    <https://docutils.sourceforge.io/docs/ref/rst/directives.html#include-options>
+    """
+    if "end-line" in options or "start-line" in options:
+        lines = contents.splitlines()
+        if i := options.get("end-line"):
+            lines = lines[: int(i)]
+        if i := options.get("start-line"):
+            lines = lines[int(i) :]
+        contents = "\n".join(lines)
+    if x := options.get("end-before"):
+        contents = contents[: contents.index(x)]
+    if x := options.get("start-after"):
+        contents = contents[contents.index(x) + len(x) :]
+    return contents
+
+
 def _rst_admonitions(contents: str, source_file: Path | None) -> str:
     """
     Convert reStructuredText admonitions - a bit tricky because they may already be indented themselves.
@@ -370,6 +403,7 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
         type = m.group("type")
         val = m.group("val").strip()
         contents = dedent(m.group("contents")).strip()
+        contents, options = _rst_extract_options(contents)
 
         if type == "include":
             loc = source_file or Path(".")
@@ -378,7 +412,12 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
             except OSError as e:
                 warnings.warn(f"Cannot include {val!r}: {e}")
                 included = "\n"
+            try:
+                included = _rst_include_trim(included, options) + "\n"
+            except ValueError as e:
+                warnings.warn(f"Failed to process include options for {val!r}: {e}")
             included = _rst_admonitions(included, loc.parent / val)
+            included = embed_images(included, loc.parent / val)
             return indent(included, ind)
         if type == "math":
             return f"{ind}$${val}{contents}$$\n"

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/extract.py

@@ -3,6 +3,7 @@ This module handles the interaction with Python's module system,
 that is it loads the correct module based on whatever the user specified,
 and provides the rest of pdoc with some additional module metadata.
 """
+
 from __future__ import annotations
 
 from collections.abc import Iterable

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/search.py

@@ -41,6 +41,7 @@ to 27kB.
 
 If you wish to disable the search functionality, you can pass `--no-search` when invoking pdoc.
 """
+
 from __future__ import annotations
 
 from collections.abc import Callable

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/templates/math.html.jinja2

@@ -10,7 +10,6 @@
         }
     };
 </script>
-<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
 <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
 <script>
     /* Re-invoke MathJax when DOM content changes, for example during search. */
@@ -24,5 +23,6 @@
 <style>
     mjx-container {
         overflow-x: auto;
+        overflow-y: hidden;
     }
 </style>

{pdoc-14.4.0 → pdoc-14.5.1}/pdoc/web.py

@@ -5,6 +5,7 @@ We want to keep the number of dependencies as small as possible,
 so we are content with the builtin `http.server` module.
 It is a bit unergonomic compared to let's say flask, but good enough for our purposes.
 """
+
 from __future__ import annotations
 
 from collections.abc import Iterable

{pdoc-14.4.0 → pdoc-14.5.1/pdoc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.4.0
+Version: 14.5.1
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -24,8 +24,22 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 License-File: LICENSE
+Requires-Dist: Jinja2>=2.11.0
+Requires-Dist: pygments>=2.12.0
+Requires-Dist: MarkupSafe
+Requires-Dist: astunparse; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-pygments; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pygments>=2.14.0; extra == "dev"
+Requires-Dist: pdoc-pyo3-sample-library==1.0.11; extra == "dev"
 
 <p align="center">
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
@@ -95,10 +109,6 @@ As an open source project, pdoc welcomes contributions of all forms.
 
 [![Dev Guide](https://shields.mitmproxy.org/badge/dev_docs-CONTRIBUTING.md-blue)](https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md)
 
-Also, please feel free to join our developer Slack!
-
-[![Slack Developer Chat](https://shields.mitmproxy.org/badge/slack-mitmproxy-E01563.svg)](http://slack.mitmproxy.org/)
-
 
 ## pdoc vs. pdoc3
 

pdoc-14.5.1/test/test_docstrings.py

@@ -0,0 +1,89 @@
+from pathlib import Path
+
+from hypothesis import given
+from hypothesis.strategies import text
+import pytest
+
+from pdoc import docstrings
+
+# The important tests are in test_snapshot.py (and, by extension, testdata/)
+# mostly some fuzzing here.
+
+
+here = Path(__file__).parent.absolute()
+
+
+@given(text())
+def test_google(s):
+    ret = docstrings.google(s)
+    assert not s or ret
+
+
+@given(text())
+def test_numpy(s):
+    ret = docstrings.numpy(s)
+    assert not s or ret
+
+
+@given(text())
+def test_rst(s):
+    ret = docstrings.rst(s, None)
+    assert not s or ret
+
+
+@given(text())
+def test_rst_extract_options_fuzz(s):
+    content, options = docstrings._rst_extract_options(s)
+    assert not s or content or options
+
+
+def test_rst_extract_options():
+    content = (
+        ":alpha: beta\n"
+        ":charlie:delta:foxtrot\n"
+        "rest of content\n"
+        ":option ignored: as follows content\n"
+    )
+    content, options = docstrings._rst_extract_options(content)
+    assert options == {
+        "alpha": "beta",
+        "charlie": "delta:foxtrot",
+    }
+    assert content == ("\nrest of content\n" ":option ignored: as follows content\n")
+
+
+def test_rst_include_trim_lines():
+    content = "alpha\nbeta\ncharlie\ndelta\necho"
+    trimmed = docstrings._rst_include_trim(
+        content, {"start-line": "2", "end-line": "4"}
+    )
+    assert trimmed == "charlie\ndelta"
+
+
+def test_rst_include_trim_pattern():
+    content = "alpha\nbeta\ncharlie\ndelta\necho"
+    trimmed = docstrings._rst_include_trim(
+        content, {"start-after": "beta", "end-before": "echo"}
+    )
+    assert trimmed == "\ncharlie\ndelta\n"
+
+
+def test_rst_include_trim_mixture():
+    content = "alpha\nbeta\ncharlie\ndelta\necho"
+    trimmed = docstrings._rst_include_trim(
+        content, {"start-after": "beta", "end-line": "4"}
+    )
+    assert trimmed == "\ncharlie\ndelta"
+
+
+def test_rst_include_nonexistent():
+    with pytest.warns(UserWarning, match="Cannot include 'nonexistent.txt'"):
+        docstrings.rst(".. include:: nonexistent.txt", None)
+
+
+def test_rst_include_invalid_options():
+    with pytest.warns(UserWarning, match="Failed to process include options"):
+        docstrings.rst(
+            ".. include:: ../README.md\n   :start-line: invalid",
+            here / "test_docstrings.py",
+        )

pdoc-14.4.0/test/test_docstrings.py

@@ -1,31 +0,0 @@
-from hypothesis import given
-from hypothesis.strategies import text
-import pytest
-
-from pdoc import docstrings
-
-# The important tests are in test_snapshot.py (and, by extension, testdata/)
-# only some fuzzing here.
-
-
-@given(text())
-def test_google(s):
-    ret = docstrings.google(s)
-    assert not s or ret
-
-
-@given(text())
-def test_numpy(s):
-    ret = docstrings.numpy(s)
-    assert not s or ret
-
-
-@given(text())
-def test_rst(s):
-    ret = docstrings.rst(s, None)
-    assert not s or ret
-
-
-def test_rst_include_nonexistent():
-    with pytest.warns(UserWarning, match="Cannot include 'nonexistent.txt'"):
-        docstrings.rst(".. include:: nonexistent.txt", None)