pdoc 14.3.0__tar.gz → 14.5.0__tar.gz

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

@@ -5,6 +5,27 @@
 ## Unreleased: pdoc next
 
 
+## 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
+
+ - Private methods can now be included in the documentation by adding `@public` to the docstring.
+   This complements the existing `@private` annotation.
+   ([#655](https://github.com/mitmproxy/pdoc/pull/655), @tmeyier)
+ - pdoc now correctly detects the source file for wrapped functions.
+   ([#657](https://github.com/mitmproxy/pdoc/pull/657), @tmeyier)
+ - Fixed a bug where memory addresses were not removed from output.
+   ([#663](https://github.com/mitmproxy/pdoc/pull/663), @mhils)
+
 ## 2023-12-22: pdoc 14.3.0
 
  - Improve rendering of `.pyi` type stubs containing `@typing.overload`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.3.0
+Version: 14.5.0
 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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/pdoc/__init__.py

@@ -176,18 +176,21 @@ class GoldenRetriever(Dog):
 
 The public interface of a module is determined through one of two
 ways.
-
 - If `__all__` is defined in the module, then all identifiers in that list will be considered public.
    No other identifiers will be considered public.
-- If `__all__` is not defined, then pdoc will consider all members public that
-   1. do not start with an underscore,
-   2. don't have `@private` in their docstring,
-   2. and are defined in the current module (i.e. they are not imported).
+- If `__all__` is not defined, then pdoc will consider all items public that do not start with an
+  underscore and that are defined in the current module (i.e. they are not imported).
+
+If you want to override the default behavior for a particular item,
+you can do so by including an annotation in its docstring:
+
+- `@private` hides an item unconditionally.
+- <code>&#64;public</code> shows an item unconditionally.
 
-In general, we recommend keeping these conventions:
+In general, we recommend keeping the following conventions:
 
 - If you want to document a private member, consider making it public.
-- If you want to hide a public member, consider making it private or add `@private` to their docstring,
+- If you want to hide a public member, consider making it private.
 - 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.
 
@@ -280,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?
@@ -459,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.3.0"  # this is read from setup.py
+__version__ = "14.5.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.3.0 → pdoc-14.5.0}/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
@@ -887,6 +888,8 @@ class Function(Doc[types.FunctionType]):
             unwrapped = func.__func__  # type: ignore
         elif isinstance(func, singledispatchmethod):
             unwrapped = func.func  # type: ignore
+        elif hasattr(func, "__wrapped__"):
+            unwrapped = func.__wrapped__
         else:
             unwrapped = func
         super().__init__(modulename, qualname, unwrapped, taken_from)
@@ -1028,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.
     
@@ -1139,7 +1144,7 @@ class Variable(Doc[None]):
             warnings.warn(f"repr({self.fullname}) raised an exception ({e!r})")
             return ""
 
-        pretty = re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", pretty)
+        pretty = _remove_memory_addresses(pretty)
         return pretty
 
     @cached_property
@@ -1180,7 +1185,8 @@ class _PrettySignature(inspect.Signature):
         render_pos_only_separator = False
         render_kw_only_separator = True
         for param in self.parameters.values():
-            formatted = re.sub(r" at 0x[0-9a-fA-F]+(?=>$)", "", str(param))
+            formatted = str(param)
+            formatted = _remove_memory_addresses(formatted)
 
             kind = param.kind
 
@@ -1298,3 +1304,8 @@ def _safe_getdoc(obj: Any) -> str:
         return ""
     else:
         return doc.strip()
+
+
+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.3.0 → pdoc-14.5.0}/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
@@ -32,7 +33,6 @@ if TYPE_CHECKING:
 def get_source(obj: Any) -> str:
     """
     Returns the source code of the Python object `obj` as a str.
-    This tries to first unwrap the method if it is wrapped and then calls `inspect.getsource`.
 
     If this fails, an empty string is returned.
     """
@@ -52,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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0}/pdoc/templates/default/module.html.jinja2

@@ -209,7 +209,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% enddefaultmacro %}
 {% defaultmacro docstring(var) %}
     {% if var.docstring %}
-        <div class="docstring">{{ var.docstring | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
+        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro nav_members(members) %}
@@ -239,10 +239,13 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     Implementing this as a macro makes it very easy to override with a custom template, see
     https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.
     #}
-    {% if not include_undocumented and not doc.docstring %}
-        {# hide members that are undocumented if include_undocumented has been toggled off. #}
-    {% elif doc.docstring and "@private" in doc.docstring %}
+    {% if "@private" in doc.docstring %}
         {# hide members explicitly marked as @private #}
+    {% elif "@public" in doc.docstring %}
+        {# show members explicitly marked as @public #}
+        true
+    {% elif not include_undocumented and not doc.docstring %}
+        {# hide members that are undocumented if include_undocumented has been toggled off. #}
     {% elif doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
         {# show constructors that have a docstring or at least one extra argument #}
         true

{pdoc-14.3.0 → pdoc-14.5.0}/pdoc/templates/math.html.jinja2

@@ -24,5 +24,6 @@
 <style>
     mjx-container {
         overflow-x: auto;
+        overflow-y: hidden;
     }
 </style>

{pdoc-14.3.0 → pdoc-14.5.0}/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.3.0 → pdoc-14.5.0/pdoc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.3.0
+Version: 14.5.0
 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.3.0 → pdoc-14.5.0}/test/test_doc.py

@@ -175,3 +175,13 @@ def test_default_value_masks_env_vars(monkeypatch):
         assert v2.default_value_str == "'42.0.1'"
     finally:
         _environ_lookup.cache_clear()
+
+
+def test_source_file_method():
+    mod = extract.load_module(extract.parse_spec(here / "testdata" / "demo_long.py"))
+
+    m = Module(mod)
+
+    assert m.members["Foo"].members["a_cached_function"].source_file == (
+        here / "testdata" / "demo_long.py"
+    )

pdoc-14.5.0/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.3.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)