update pdoc doc generation

Author: FynnBe

.github/workflows/build.yaml

@@ -167,17 +167,8 @@ jobs:
           python-version: '3.12'
           cache: 'pip'
       - run: pip install -e .[dev]
-      - id: get_version
-        run: python -c 'import bioimageio.core;print(f"version={bioimageio.core.__version__}")' >> $GITHUB_OUTPUT
       - name: Generate developer docs
-        run: |
-          pdoc \
-          --docformat google \
-          --logo https://bioimage.io/static/img/bioimage-io-logo.svg \
-          --logo-link https://bioimage.io/ \
-          --favicon https://bioimage.io/static/img/bioimage-io-icon-small.svg \
-          --footer-text 'bioimageio.core ${{steps.get_version.outputs.version}}' \
-          -o ./dist bioimageio.core
+        run: ./scripts/pdoc/run.sh
       - run: cp README.md ./dist/README.md
       - name: copy rendered presentations
         run: |

pyproject.toml

@@ -1,13 +1,21 @@
 [tool.black]
 line-length = 88
-extend_exclude = "^/presentations/"
+extend_exclude = "^/presentations/ | ^/scripts/pdoc/original.py | ^/scripts/pdoc/patched.py"
 target-version = ["py38", "py39", "py310", "py311", "py312"]
+preview = true
 
 [tool.pyright]
-exclude = ["**/node_modules", "**/__pycache__", "tests/old_*", "presentations"]
+exclude = [
+    "**/__pycache__",
+    "**/node_modules",
+    "presentations",
+    "scripts/pdoc/original.py",
+    "scripts/pdoc/patched.py",
+    "tests/old_*",
+]
 include = ["bioimageio", "scripts", "tests"]
 pythonPlatform = "All"
-pythonVersion = "3.13"
+pythonVersion = "3.12"
 reportDuplicateImport = "error"
 reportImplicitStringConcatenation = "error"
 reportIncompatibleMethodOverride = true
@@ -35,8 +43,13 @@ addopts = "--cov=bioimageio --cov-report=xml -n auto --capture=no --doctest-modu
 
 [tool.ruff]
 line-length = 88
+target-version = "py312"
 include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
-exclude = ["presentations"]
+exclude = [
+    "presentations",
+    "scripts/pdoc/original.py",
+    "scripts/pdoc/patched.py",
+]
 
 [tool.coverage.report]
 exclude_also = ["if TYPE_CHECKING:", "assert_never\\("]

scripts/pdoc/create_pydantic_patch.sh

@@ -0,0 +1,25 @@
+pydantic_root=$(python -c "import pydantic;from pathlib import Path;print(Path(pydantic.__file__).parent)")
+main=$pydantic_root'/main.py'
+original="$(dirname "$0")/original.py"
+patched="$(dirname "$0")/patched.py"
+
+if [ -e $original ]
+then
+    echo "found existing $original"
+else
+    cp --verbose $main $original
+fi
+
+if [ -e $patched ]
+then
+    echo "found existing $patched"
+else
+    cp --verbose $main $patched
+    echo "Please update $patched, then press enter to continue"
+    read
+fi
+
+patch_file="$(dirname "$0")/mark_pydantic_attrs_private.patch"
+diff -au $original $patched > $patch_file
+echo "content of $patch_file:"
+cat $patch_file

scripts/pdoc/mark_pydantic_attrs_private.patch

@@ -0,0 +1,28 @@
+--- ./original.py	2024-11-08 15:18:37.493768700 +0100
++++ ./patched.py	2024-11-08 15:13:54.288887700 +0100
+@@ -121,14 +121,14 @@
+     # `GenerateSchema.model_schema` to work for a plain `BaseModel` annotation.
+ 
+     model_config: ClassVar[ConfigDict] = ConfigDict()
+-    """
++    """@private
+     Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].
+     """
+ 
+     # Because `dict` is in the local namespace of the `BaseModel` class, we use `Dict` for annotations.
+     # TODO v3 fallback to `dict` when the deprecated `dict` method gets removed.
+     model_fields: ClassVar[Dict[str, FieldInfo]] = {}  # noqa: UP006
+-    """
++    """@private
+     Metadata about the fields defined on the model,
+     mapping of field names to [`FieldInfo`][pydantic.fields.FieldInfo] objects.
+ 
+@@ -136,7 +136,7 @@
+     """
+ 
+     model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}  # noqa: UP006
+-    """A dictionary of computed field names and their corresponding `ComputedFieldInfo` objects."""
++    """@private A dictionary of computed field names and their corresponding `ComputedFieldInfo` objects."""
+ 
+     __class_vars__: ClassVar[set[str]]
+     """The names of the class variables defined on the model."""

scripts/pdoc/run.sh

@@ -0,0 +1,16 @@
+cd "$(dirname "$0")"  # cd to folder this script is in
+
+# patch pydantic to hide pydantic attributes that somehow show up in the docs
+# (not even as inherited, but as if the documented class itself would define them)
+pydantic_main=$(python -c "import pydantic;from pathlib import Path;print(Path(pydantic.__file__).parent / 'main.py')")
+
+patch --verbose --forward -p1 $pydantic_main < mark_pydantic_attrs_private.patch
+
+cd ../..  # cd to repo root
+pdoc \
+    --docformat google \
+    --logo "https://bioimage.io/static/img/bioimage-io-logo.svg" \
+    --logo-link "https://bioimage.io/" \
+    --favicon "https://bioimage.io/static/img/bioimage-io-icon-small.svg" \
+    --footer-text "bioimageio.core $(python -c 'import bioimageio.core;print(bioimageio.core.__version__)')" \
+    -o ./dist bioimageio.core bioimageio.spec  # generate bioimageio.spec as well for references