From e5ccb4f4a5b14170307ca0e5a5bc151d25830720 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 13 Mar 2024 20:17:23 +0100 Subject: [PATCH 1/8] ci: Fix CI workflow --- .github/workflows/ci.yml | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f3b59817..384bf7cc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,29 +55,6 @@ jobs: - name: Check for breaking changes in the API run: make check-api - exclude-test-jobs: - runs-on: ubuntu-latest - outputs: - jobs: ${{ steps.exclude-jobs.outputs.jobs }} - steps: - - id: exclude-jobs - run: | - if ${{ github.repository_owner == 'pawamoy-insiders' }}; then - echo 'jobs=[ - {"os": "macos-latest"}, - {"os": "windows-latest"}, - {"python-version": "3.9"}, - {"python-version": "3.10"}, - {"python-version": "3.11"}, - {"python-version": "3.12"} - ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT - else - echo 'jobs=[]' >> $GITHUB_OUTPUT - fi - - - name: Check for breaking changes in the API - run: pdm run duty check-api - exclude-test-jobs: runs-on: ubuntu-latest outputs: From 7c8b885fa2b704e719016acb35791723ea3a496a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Mar 2024 16:11:04 +0100 Subject: [PATCH 2/8] refactor: Maintain original Pygments color for cross-refs in signatures --- .../python/templates/material/style.css | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index 82086b8f..805c64c3 100644 --- a/src/mkdocstrings_handlers/python/templates/material/style.css +++ b/src/mkdocstrings_handlers/python/templates/material/style.css @@ -105,4 +105,9 @@ code.doc-symbol-module { code.doc-symbol-module::after { content: "mod"; -} \ No newline at end of file +} + +.doc-signature .autorefs { + color: inherit; + border-bottom: 1px dotted currentcolor; +} From 1fc4cb54ab1f7dede1eb655bd98c5a9866efd361 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Mar 2024 16:11:15 +0100 Subject: [PATCH 3/8] docs: Use current color for autorefs external link icon --- docs/css/mkdocstrings.css | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css index 727a614c..03c39d33 100644 --- a/docs/css/mkdocstrings.css +++ b/docs/css/mkdocstrings.css @@ -18,10 +18,10 @@ a.autorefs-external::after { height: 1em; width: 1em; - background-color: var(--md-typeset-a-color); + background-color: currentColor; } a.external:hover::after, a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); -} \ No newline at end of file +} From d62daa71d17be1790d1b61ec83eabcc43db7a684 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Mar 2024 16:11:29 +0100 Subject: [PATCH 4/8] docs: Document customization of syntax highlight in signatures --- docs/usage/customization.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 14721092..2567870e 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -348,10 +348,36 @@ Available context: - `section`: The [DocstringSection][griffe.docstrings.dataclasses.DocstringSection] instance (see `DocstringSection*` subclasses). -## Style recommendations +### Syntax highlight in signatures + +You can customize the colors in syntax highlighted signatures. +If you are using the [Material for MkDocs] theme, +here are some customization examples: - +```css +/* Fancier color for operators such as * and |. */ +.doc-signature .o { + color: var(--md-code-hl-special-color); +} +/* Fancier color for constants such as None, True, and False. */ +.doc-signature .kc { + color: var(--md-code-hl-constant-color); +} + +/* Fancier color for built-in types (only useful when cross-references are used). */ +.doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"], +.doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] { + color: var(--md-code-hl-constant-color); +} +``` + +For other themes, use their own CSS variables, +or use plain colors such as `violet` or `#2987f2`. + +## Style recommendations + +[](){#recommended-style-material} ### Material Here are some CSS rules for the [Material for MkDocs] theme: @@ -360,8 +386,7 @@ Here are some CSS rules for the [Material for MkDocs] theme: --8<-- "docs/css/mkdocstrings.css" ``` - - +[](){#recommended-style-readthedocs} ### ReadTheDocs Here are some CSS rules for the built-in ReadTheDocs theme: From f798a1e19dbac548420dcbe1172e9a49232b615b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Mar 2024 16:11:41 +0100 Subject: [PATCH 5/8] refactor: Allow first name in a separate signature to be highlighted as a function name --- src/mkdocstrings_handlers/python/rendering.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index b1cb7ffc..878b74aa 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -166,6 +166,15 @@ def do_format_signature( ), ) + # Since we highlight the signature without `def`, + # Pygments sees it as a function call and not a function definition. + # The result is that the function name is not parsed as such, + # but instead as a regular name: `n` CSS class instead of `nf`. + # To fix it, we replace the first occurrence of an `n` CSS class + # with an `nf` one, unless we found `nf` already. + if signature.find('class="nf"') == -1: + signature = signature.replace('class="n"', 'class="nf"', 1) + if stash: for key, value in stash.items(): signature = re.sub(rf"\b{key}\b", value, signature) From 3cf7055a6620e5121f01ca65e589ce8992e8d745 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Mar 2024 16:11:51 +0100 Subject: [PATCH 6/8] docs: Fix link to Griffe extension in insiders page --- docs/insiders/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 9a0ae309..123fe42d 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -59,7 +59,7 @@ data_source = [ "docs/insiders/goals.yml", ("griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"), ("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"), - ("griffe-typing-deprecated", "https://mkdocstrings.github.io/griffe-typing-deprecated/", "insiders/goals.yml"), + ("griffe-warnings-deprecated", "https://mkdocstrings.github.io/griffe-warnings-deprecated/", "insiders/goals.yml"), ] ``` From bd7349714059afb1295e743dbc82380fa797a032 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 2 Apr 2024 18:43:59 +0200 Subject: [PATCH 7/8] fix: Don't try loading packages from relative paths Issue-145: https://github.com/mkdocstrings/python/issues/145 --- src/mkdocstrings_handlers/python/handler.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index c5217e98..fa8e384c 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -283,8 +283,16 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem: try: for pre_loaded_module in final_config.get("preload_modules") or []: if pre_loaded_module not in self._modules_collection: - loader.load(pre_loaded_module, find_stubs_package=final_config["find_stubs_package"]) - loader.load(module_name, find_stubs_package=final_config["find_stubs_package"]) + loader.load( + pre_loaded_module, + try_relative_path=False, + find_stubs_package=final_config["find_stubs_package"], + ) + loader.load( + module_name, + try_relative_path=False, + find_stubs_package=final_config["find_stubs_package"], + ) except ImportError as error: raise CollectionError(str(error)) from error unresolved, iterations = loader.resolve_aliases( From d3b05ade6f35d914feb44317a48ed78f0e0d5391 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 2 Apr 2024 18:48:07 +0200 Subject: [PATCH 8/8] chore: Prepare release 1.9.1 --- CHANGELOG.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bc0d6a2..5a06cd76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ 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). +## [1.9.1](https://github.com/mkdocstrings/python/releases/tag/1.9.1) - 2024-04-02 + +[Compare with 1.9.0](https://github.com/mkdocstrings/python/compare/1.9.0...1.9.1) + +### Bug Fixes + +- Don't try loading packages from relative paths ([bd73497](https://github.com/mkdocstrings/python/commit/bd7349714059afb1295e743dbc82380fa797a032) by Timothée Mazzucotelli). [Issue-145](https://github.com/mkdocstrings/python/issues/145) + +### Code Refactoring + +- Allow first name in a separate signature to be highlighted as a function name ([f798a1e](https://github.com/mkdocstrings/python/commit/f798a1e19dbac548420dcbe1172e9a49232b615b) by Timothée Mazzucotelli). +- Maintain original Pygments color for cross-refs in signatures ([7c8b885](https://github.com/mkdocstrings/python/commit/7c8b885fa2b704e719016acb35791723ea3a496a) by Timothée Mazzucotelli). + ## [1.9.0](https://github.com/mkdocstrings/python/releases/tag/1.9.0) - 2024-03-13 [Compare with 1.8.0](https://github.com/mkdocstrings/python/compare/1.8.0...1.9.0)