Merge branch 'main' into end-to-end-tests

Author: pawamoy

.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 1.1.4
+_commit: 1.2.0
 _src_path: gh:mkdocstrings/handler-template
 author_email: [email protected]
 author_fullname: Timothée Mazzucotelli

.github/workflows/ci.yml

@@ -29,13 +29,16 @@ jobs:
     - name: Fetch all tags
       run: git fetch --depth=1 --tags
 
-    - name: Set up Python
+    - name: Setup Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.11"
+        python-version: "3.12"
 
-    - name: Install uv
-      run: pip install uv
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-dependency-glob: pyproject.toml
 
     - name: Install dependencies
       run: make setup
@@ -63,11 +66,11 @@ jobs:
           echo 'jobs=[
             {"os": "macos-latest"},
             {"os": "windows-latest"},
-            {"python-version": "3.9"},
             {"python-version": "3.10"},
             {"python-version": "3.11"},
             {"python-version": "3.12"},
-            {"python-version": "3.13"}
+            {"python-version": "3.13"},
+            {"python-version": "3.14"}
           ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT
         else
           echo 'jobs=[
@@ -87,31 +90,35 @@ jobs:
         - macos-latest
         - windows-latest
         python-version:
-        - "3.8"
         - "3.9"
         - "3.10"
         - "3.11"
         - "3.12"
         - "3.13"
+        - "3.14"
         resolution:
         - highest
         - lowest-direct
         exclude: ${{ fromJSON(needs.exclude-test-jobs.outputs.jobs) }}
     runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ matrix.python-version == '3.13' }}
+    continue-on-error: ${{ matrix.python-version == '3.14' }}
 
     steps:
     - name: Checkout
       uses: actions/checkout@v4
 
-    - name: Set up Python
+    - name: Setup Python
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         allow-prereleases: true
 
-    - name: Install uv
-      run: pip install uv
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-dependency-glob: pyproject.toml
+        cache-suffix: py${{ matrix.python-version }}
 
     - name: Install dependencies
       env:

.github/workflows/release.yml

@@ -14,32 +14,30 @@ jobs:
     - name: Fetch all tags
       run: git fetch --depth=1 --tags
     - name: Setup Python
-      uses: actions/setup-python@v4
-    - name: Install build
-      if: github.repository_owner == 'pawamoy-insiders'
-      run: python -m pip install build
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v3
     - name: Build dists
       if: github.repository_owner == 'pawamoy-insiders'
-      run: python -m build
+      run: uv tool run --from build pyproject-build
     - name: Upload dists artifact
       uses: actions/upload-artifact@v4
       if: github.repository_owner == 'pawamoy-insiders'
       with:
         name: python-insiders
         path: ./dist/*
-    - name: Install git-changelog
-      if: github.repository_owner != 'pawamoy-insiders'
-      run: pip install git-changelog
     - name: Prepare release notes
       if: github.repository_owner != 'pawamoy-insiders'
-      run: git-changelog --release-notes > release-notes.md
+      run: uv tool run git-changelog --release-notes > release-notes.md
     - name: Create release with assets
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       if: github.repository_owner == 'pawamoy-insiders'
       with:
         files: ./dist/*
     - name: Create release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       if: github.repository_owner != 'pawamoy-insiders'
       with:
         body_path: release-notes.md

.gitignore

@@ -15,6 +15,7 @@
 /.pdm-build/
 /htmlcov/
 /site/
+uv.lock
 
 # cache
 .cache/

.gitpod.dockerfile

@@ -5,6 +5,68 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.12.2](https://github.com/mkdocstrings/python/releases/tag/1.12.2) - 2024-10-19
+
+<small>[Compare with 1.12.1](https://github.com/mkdocstrings/python/compare/1.12.1...1.12.2)</small>
+
+### Bug Fixes
+
+- Always render cross-references outside of signatures ([73f11dc](https://github.com/mkdocstrings/python/commit/73f11dcc584a672af7e17738cba08a50f119176a) by Timothée Mazzucotelli). [Issue-mkdocstrings#700](https://github.com/mkdocstrings/mkdocstrings/issues/700)
+
+## [1.12.1](https://github.com/mkdocstrings/python/releases/tag/1.12.1) - 2024-10-14
+
+<small>[Compare with 1.12.0](https://github.com/mkdocstrings/python/compare/1.12.0...1.12.1)</small>
+
+### Bug Fixes
+
+- Don't escape parameter default values ([9dee4d4](https://github.com/mkdocstrings/python/commit/9dee4d4f8e1258e99c19dc7b2b18d3e9090de79b) by Timothée Mazzucotelli). [Issue-191](https://github.com/mkdocstrings/python/issues/191)
+
+## [1.12.0](https://github.com/mkdocstrings/python/releases/tag/1.12.0) - 2024-10-12
+
+<small>[Compare with 1.11.1](https://github.com/mkdocstrings/python/compare/1.11.1...1.12.0)</small>
+
+### Build
+
+- Drop support for Python 3.8 ([6615c91](https://github.com/mkdocstrings/python/commit/6615c91cdc035bc0c2fdd12f3952ff84f5e1c04e) by Timothée Mazzucotelli).
+
+### Features
+
+- Auto-summary of members ([7f9757d](https://github.com/mkdocstrings/python/commit/7f9757d1584555edebc56f1aefe6cc8242e6c8bb) by Timothée Mazzucotelli).
+- Render function overloads ([0f2c25c](https://github.com/mkdocstrings/python/commit/0f2c25c9ed7f6c5c93ff13df214f02edfd3a4cb1) by Timothée Mazzucotelli).
+- Parameter headings, more automatic cross-references ([0176b83](https://github.com/mkdocstrings/python/commit/0176b83f21ae02d345489c93cca3baf51f8bc58c) by Timothée Mazzucotelli).
+
+### Code Refactoring
+
+- Declare default CSS symbol colors under :host as well ([3b9dba2](https://github.com/mkdocstrings/python/commit/3b9dba2709a8668e379c6ce1536cb1714971b3f4) by James McDonnell). [PR-186](https://github.com/mkdocstrings/python/pull/186)
+
+## [1.11.1](https://github.com/mkdocstrings/python/releases/tag/1.11.1) - 2024-09-03
+
+<small>[Compare with 1.11.0](https://github.com/mkdocstrings/python/compare/1.11.0...1.11.1)</small>
+
+### Code Refactoring
+
+- Prepare `relative_crossrefs` and `scoped_crossrefs` insiders features ([dd8b014](https://github.com/mkdocstrings/python/commit/dd8b014a8ab3decc31d4b08bc22fe68577e1a02c) by Timothée Mazzucotelli).
+
+## [1.11.0](https://github.com/mkdocstrings/python/releases/tag/1.11.0) - 2024-09-03
+
+<small>[Compare with 1.10.9](https://github.com/mkdocstrings/python/compare/1.10.9...1.11.0)</small>
+
+### Features
+
+- Hook into autorefs to provide context around cross-ref errors ([bb4be5b](https://github.com/mkdocstrings/python/commit/bb4be5be1b85be50f46c7889231a2d4a3bd05165) by Timothée Mazzucotelli).
+
+## [1.10.9](https://github.com/mkdocstrings/python/releases/tag/1.10.9) - 2024-08-30
+
+<small>[Compare with 1.10.8](https://github.com/mkdocstrings/python/compare/1.10.8...1.10.9)</small>
+
+### Build
+
+- Explicitly depend on mkdocs-autorefs to be able to specify lower bound ([2299ab5](https://github.com/mkdocstrings/python/commit/2299ab55641585d65babe0e116a6465b4736dcd9) by Timothée Mazzucotelli).
+
+### Code Refactoring
+
+- Use new autorefs syntax ([68cb72f](https://github.com/mkdocstrings/python/commit/68cb72f62253f54146ece621345b36c90d712913) by Timothée Mazzucotelli).
+
 ## [1.10.8](https://github.com/mkdocstrings/python/releases/tag/1.10.8) - 2024-08-14
 
 <small>[Compare with 1.10.7](https://github.com/mkdocstrings/python/compare/1.10.7...1.10.8)</small>

.gitpod.yml

@@ -23,12 +23,11 @@ make setup
 > You can install it with:
 >
 > ```bash
-> python3 -m pip install --user pipx
-> pipx install uv
+> curl -LsSf https://astral.sh/uv/install.sh | sh
 > ```
 >
 > Now you can try running `make setup` again,
-> or simply `uv install`.
+> or simply `uv sync`.
 
 You now have the dependencies installed.
 

CHANGELOG.md

@@ -1,4 +1,4 @@
-target-version = "py38"
+target-version = "py39"
 line-length = 120
 
 [lint]

CONTRIBUTING.md

@@ -8,5 +8,6 @@
 [Spacy's documentation]: https://spacy.io/api/doc/
 [Black]: https://pypi.org/project/black/ 
 [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material
+[Ruff]: https://docs.astral.sh/ruff
 
 *[ToC]: Table of Contents

config/ruff.toml

@@ -2,6 +2,37 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.9.0 <small>September 03, 2024</small> { id="1.9.0" }
+
+- [Relative cross-references][relative_crossrefs]
+- [Scoped cross-references][scoped_crossrefs]
+
+### 1.8.3 <small>June 19, 2024</small> { id="1.8.3" }
+
+- Update code for Griffe 0.46+ to avoid deprecation warnings
+
+### 1.8.2 <small>May 09, 2024</small> { id="1.8.2" }
+
+- Don't render cross-refs for default values when signatures aren't separated
+
+### 1.8.1 <small>April 19, 2024</small> { id="1.8.1" }
+
+- Render enumeration instance name instead of just "value", allowing proper cross-reference
+
+### 1.8.0 <small>March 24, 2024</small> { id="1.8.0" }
+
+- [Annotations modernization][modernize_annotations]
+
+### 1.7.0 <small>March 24, 2024</small> { id="1.7.0" }
+
+- [Class inheritance diagrams with Mermaid][show_inheritance_diagram]
+
+### 1.6.0 <small>January 30, 2024</small> { id="1.6.0" }
+
+- Render cross-references to parameters documentation in signatures and attribute values.
+- Add [`parameter_headings`][parameter_headings] option to render headings for parameters (enabling permalinks and ToC/inventory entries).
+- Render cross-references for default parameter values in signatures.
+
 ### 1.5.1 <small>September 12, 2023</small> { id="1.5.1" }
 
 - Prevent empty auto-summarized Methods section.

devdeps.txt

@@ -16,9 +16,29 @@ goals:
       since: 2023/08/20
     - name: Automatic rendering of function signature overloads
       since: 2023/09/05
+    - name: Parameter headings
+      ref: /usage/configuration/headings/#parameter_headings
+      since: 2024/01/30
+    - name: Automatic cross-references to parameters
+      ref: /usage/configuration/headings/#parameter_headings
+      since: 2024/01/30
+    - name: Automatic cross-references for default parameter values in signatures
+      since: 2024/01/30
   1500:
     name: HyperLamp Navigation Tips
-    features: []
+    features:
+    - name: Class inheritance diagrams with Mermaid
+      ref: /usage/configuration/general/#show_inheritance_diagram
+      since: 2024/03/24
+    - name: Annotations modernization
+      ref: /usage/configuration/signatures/#modernize_annotations
+      since: 2024/03/24
   2000:
     name: FusionDrive Ejection Configuration
-    features: []
+    features:
+    - name: Relative cross-references
+      ref: /usage/configuration/docstrings/#relative_crossrefs
+      since: 2024/09/03
+    - name: Scoped cross-references
+      ref: /usage/configuration/docstrings/#scoped_crossrefs
+      since: 2024/09/03

docs/.glossary.md

@@ -145,7 +145,7 @@
               "default": false
             },
             "separate_signature": {
-              "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.",
+              "title": "Whether to put the whole signature in a code block below the heading. If a formatter (Black or Ruff) is installed, the signature is also formatted using it.",
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature",
               "type": "boolean",
               "default": false

docs/insiders/changelog.md

@@ -0,0 +1,19 @@
+from importlib import metadata
+
+def get_version(dist: str = "mkdocstrings-python") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+current_version: str = get_version(dist="mkdocstrings-python")
+"""Current package version."""

docs/insiders/goals.yml

@@ -0,0 +1,3 @@
+from typing import Optional, Union, List
+
+example: Optional[Union[int, List[int]]] = None