Merge branch 'main' into hooks

.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 1.2.8
+_commit: 1.4.0
 _src_path: gh:pawamoy/copier-uv
 author_email: [email protected]
 author_fullname: Timothée Mazzucotelli

.github/ISSUE_TEMPLATE/bug_report.md → .github/ISSUE_TEMPLATE/1-bug.md

@@ -53,7 +53,7 @@ PASTE TRACEBACK HERE
 python -m mkdocs_autorefs.debug  # | xclip -selection clipboard
 ```
 
-PASTE OUTPUT HERE
+PASTE MARKDOWN OUTPUT HERE
 
 ### Additional context
 <!-- Add any other relevant context about the problem here,

.github/ISSUE_TEMPLATE/3-docs.md

@@ -0,0 +1,16 @@
+---
+name: Documentation update
+about: Point at unclear, missing or outdated documentation.
+title: "docs: "
+labels: docs
+assignees: pawamoy
+---
+
+### Is something unclear, missing or outdated in our documentation?
+<!-- A clear and concise description of what the documentation issue is. Ex. I can't find an explanation on feature [...]. -->
+
+### Relevant code snippets
+<!-- If the documentation issue is related to code, please provide relevant code snippets. -->
+
+### Link to the relevant documentation section
+<!-- Add a link to the relevant section of our documentation, or any addition context. -->

.github/ISSUE_TEMPLATE/4-change.md

@@ -0,0 +1,18 @@
+---
+name: Change request
+about: Suggest any other kind of change for this project.
+title: "change: "
+assignees: pawamoy
+---
+
+### Is your change request related to a problem? Please describe.
+<!-- A clear and concise description of what the problem is. -->
+
+### Describe the solution you'd like
+<!-- A clear and concise description of what you want to happen. -->
+
+### Describe alternatives you've considered
+<!-- A clear and concise description of any alternative solutions you've considered. -->
+
+### Additional context
+<!-- Add any other context or screenshots about the change request here. -->

CHANGELOG.md

@@ -5,6 +5,29 @@ 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.1.0](https://github.com/mkdocstrings/autorefs/releases/tag/1.1.0) - 2024-08-20
+
+<small>[Compare with 1.0.1](https://github.com/mkdocstrings/autorefs/compare/1.0.1...1.1.0)</small>
+
+### Deprecations
+
+- `AUTO_REF_RE` is renamed `AUTOREF_RE` (and updated for an improved version of `fix_refs`)
+- `AutoRefInlineProcessor` is renamed `AutorefsInlineProcessor`
+
+### Features
+
+- Warn when multiple URLs are found for the same identifier ([c630354](https://github.com/mkdocstrings/autorefs/commit/c6303542018ca835f6941c070accb582f851f6b1) by Markus B). [Issue-35](https://github.com/mkdocstrings/autorefs/issues/35), [PR-50](https://github.com/mkdocstrings/autorefs/pull/50), Co-authored-by: Timothée Mazzucotelli <[email protected]>
+
+### Bug Fixes
+
+- Only log "Markdown anchors feature enabled" once ([1c9bda1](https://github.com/mkdocstrings/autorefs/commit/1c9bda1ab4f13c9a5cf5d202de755e5296729654) by Timothée Mazzucotelli). [Issue-44](https://github.com/mkdocstrings/autorefs/issues/44)
+
+### Code Refactoring
+
+- Use a custom autoref HTML tag ([e142023](https://github.com/mkdocstrings/autorefs/commit/e14202317dc13dd5eed93b5d7cfd183c87de893f) by Timothée Mazzucotelli). [PR-48](https://github.com/mkdocstrings/autorefs/pull/48)
+- Rename AutoRefInlineProcessor to AutorefsInlineProcessor ([ffcaa01](https://github.com/mkdocstrings/autorefs/commit/ffcaa0178b642e423acdc66d35f1e6b207099dc7) by Timothée Mazzucotelli).
+- Attach name to processors for easier retrieval ([036b825](https://github.com/mkdocstrings/autorefs/commit/036b825c7994b2586564e8707fbc0b3627c29569) by Timothée Mazzucotelli).
+
 ## [1.0.1](https://github.com/mkdocstrings/autorefs/releases/tag/1.0.1) - 2024-02-29
 
 <small>[Compare with 1.0.0](https://github.com/mkdocstrings/autorefs/compare/1.0.0...1.0.1)</small>

CONTRIBUTING.md

@@ -36,13 +36,11 @@ Run `make help` to see all the available actions!
 
 ## Tasks
 
-This project uses [duty](https://github.com/pawamoy/duty) to run tasks.
-A Makefile is also provided. The Makefile will try to run certain tasks
-on multiple Python versions. If for some reason you don't want to run the task
-on multiple Python versions, you run the task directly with `make run duty TASK`.
-
-The Makefile detects if a virtual environment is activated,
-so `make` will work the same with the virtualenv activated or not.
+The entry-point to run commands and tasks is the `make` Python script,
+located in the `scripts` directory. Try running `make` to show the available commands and tasks.
+The *commands* do not need the Python dependencies to be installed,
+while the *tasks* do.
+The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty).
 
 If you work in VSCode, we provide
 [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup)

README.md

@@ -5,7 +5,7 @@
 [![pypi version](https://img.shields.io/pypi/v/mkdocs-autorefs.svg)](https://pypi.org/project/mkdocs-autorefs/)
 [![conda version](https://img.shields.io/conda/vn/conda-forge/mkdocs-autorefs.svg)](https://anaconda.org/conda-forge/mkdocs-autorefs)
 [![gitpod](https://img.shields.io/badge/gitpod-workspace-708FCC.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/autorefs)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#autorefs:gitter.im)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#mkdocstrings/autorefs:gitter.im)
 
 Automatically link across pages in MkDocs.
 
@@ -47,9 +47,38 @@ We can [link to that heading][hello-world] from another page too.
 This works the same as [a normal link to that heading](../doc1.md#hello-world).
 ```
 
-Linking to a heading without needing to know the destination page can be useful if specifying that path is cumbersome, e.g. when the pages have deeply nested paths, are far apart, or are moved around frequently. And the issue is somewhat exacerbated by the fact that [MkDocs supports only *relative* links between pages](https://github.com/mkdocs/mkdocs/issues/1592).
+Linking to a heading without needing to know the destination page can be useful if specifying that path is cumbersome, e.g. when the pages have deeply nested paths, are far apart, or are moved around frequently.
 
-Note that this plugin's behavior is undefined when trying to link to a heading title that appears several times throughout the site. Currently it arbitrarily chooses one of the pages. In such cases, use [Markdown anchors](#markdown-anchors) to add unique aliases to your headings.
+### Non-unique headings
+
+When linking to a heading that appears several times throughout the site, this plugin will log a warning message stating that multiple URLs were found and that headings should be made unique, and will resolve the link using the first found URL.
+
+To prevent getting warnings, use [Markdown anchors](#markdown-anchors) to add unique aliases to your headings, and use these aliases when referencing the headings.
+
+If you cannot use Markdown anchors, for example because you inject the same generated contents in multiple locations (for example mkdocstrings' API documentation), then you can try to alleviate the warnings by enabling the `resolve_closest` option:
+
+```yaml
+plugins:
+- autorefs:
+    resolve_closest: true
+```
+
+When `resolve_closest` is enabled, and multiple URLs are found for the same identifier, the plugin will try to resolve to the one that is "closest" to the current page (the page containing the link). By closest, we mean:
+
+- URLs that are relative to the current page's URL, climbing up parents
+- if multiple URLs are relative to it, use the one at the shortest distance if possible.
+
+If multiple relative URLs are at the same distance, the first of these URLs will be used. If no URL is relative to the current page's URL, the first URL of all found URLs will be used.
+
+Examples:
+
+Current page | Candidate URLs | Relative URLs | Winner
+------------ | -------------- | ------------- | ------
+` ` | `x/#b`, `#b` | `#b` | `#b` (only one relative)
+`a/` | `b/c/#d`, `c/#d` | none | `b/c/#d` (no relative, use first one, even if longer distance)
+`a/b/` | `x/#e`, `a/c/#e`, `a/d/#e` | `a/c/#e`, `a/d/#e` (relative to parent `a/`) | `a/c/#e` (same distance, use first one)
+`a/b/` | `x/#e`, `a/c/d/#e`, `a/c/#e` | `a/c/d/#e`, `a/c/#e` (relative to parent `a/`) | `a/c/#e` (shortest distance)
+`a/b/c/` | `x/#e`, `a/#e`, `a/b/#e`, `a/b/c/d/#e`, `a/b/c/#e` | `a/b/c/d/#e`, `a/b/c/#e` | `a/b/c/#e` (shortest distance)
 
 ### Markdown anchors
 
@@ -90,7 +119,7 @@ Paragraph about foobar.
 ```md
 In any document.
 
-Check out the [paragraph about foobar][foobar-pararaph].
+Check out the [paragraph about foobar][foobar-paragraph].
 ```
 
 If you add a Markdown anchor right above a heading, this anchor will redirect to the heading itself:
@@ -143,3 +172,14 @@ You don't want to change headings and make them redundant, like `## Arch: Instal
 ```
 
 ...changing `arch` by `debian`, `gentoo`, etc. in the other pages.
+
+---
+
+You can also change the actual identifier of a heading, thanks again to the `attr_list` Markdown extension:
+
+```md
+## Install from sources { #arch-install-src }
+...
+```
+
+...though note that this will impact the URL anchor too (and therefore the permalink to the heading).

devdeps.txt

@@ -4,7 +4,7 @@ editables>=0.5
 # maintenance
 build>=1.2
 git-changelog>=2.5
-twine>=5.1; python_version < '3.13'
+twine>=5.0; python_version < '3.13'
 
 # ci
 duty>=1.4

docs/.overrides/partials/comments.html

@@ -0,0 +1,57 @@
+<!-- Giscus -->
+<!-- https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration -->
+<div id="feedback" style="display: none;">
+    <h2 id="__comments">Feedback</h2>
+    <script src="https://giscus.app/client.js"
+        data-repo="mkdocstrings/autorefs"
+        data-repo-id="MDEwOlJlcG9zaXRvcnkzMzc2NTE2NjM="
+        data-category="Documentation"
+        data-category-id="DIC_kwDOFCAnz84Chq2b"
+        data-mapping="pathname"
+        data-strict="1"
+        data-reactions-enabled="0"
+        data-emit-metadata="0"
+        data-input-position="top"
+        data-theme="preferred_color_scheme"
+        data-lang="en"
+        data-loading="lazy"
+        crossorigin="anonymous"
+        async>
+    </script>
+
+    <!-- Synchronize Giscus theme with palette -->
+    <script>
+        var giscus = document.querySelector("script[src*=giscus]")
+
+        // Set palette on initial load
+        var palette = __md_get("__palette")
+        if (palette && typeof palette.color === "object") {
+            var theme = palette.color.scheme === "slate"
+                ? "transparent_dark"
+                : "light"
+
+            // Instruct Giscus to set theme
+            giscus.setAttribute("data-theme", theme) 
+        }
+
+        // Register event handlers after documented loaded
+        document.addEventListener("DOMContentLoaded", function() {
+            var ref = document.querySelector("[data-md-component=palette]")
+            ref.addEventListener("change", function() {
+                var palette = __md_get("__palette")
+                if (palette && typeof palette.color === "object") {
+                    var theme = palette.color.scheme === "slate"
+                        ? "transparent_dark"
+                        : "light"
+
+                    // Instruct Giscus to change theme
+                    var frame = document.querySelector(".giscus-frame")
+                    frame.contentWindow.postMessage(
+                        { giscus: { setConfig: { theme } } },
+                        "https://giscus.app"
+                    )
+                }
+            })
+        })
+    </script>
+</div>

docs/index.md

@@ -1 +1,6 @@
+---
+hide:
+- feedback
+---
+
 --8<-- "README.md"

docs/js/feedback.js

@@ -0,0 +1,14 @@
+const feedback = document.forms.feedback;
+feedback.hidden = false;
+
+feedback.addEventListener("submit", function(ev) {
+    ev.preventDefault();
+    const commentElement = document.getElementById("feedback");
+    commentElement.style.display = "block";
+    feedback.firstElementChild.disabled = true;
+    const data = ev.submitter.getAttribute("data-md-value");
+    const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']");
+    if (note) {
+        note.hidden = false;
+    }
+})

docs/license.md

@@ -1,3 +1,8 @@
+---
+hide:
+- feedback
+---
+
 # License
 
 ```

duties.py

@@ -53,8 +53,8 @@ def changelog(ctx: Context, bump: str = "") -> None:
     ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog")
 
 
-@duty(pre=["check_quality", "check_types", "check_docs", "check_dependencies", "check-api"])
-def check(ctx: Context) -> None:  # noqa: ARG001
+@duty(pre=["check_quality", "check_types", "check_docs", "check-api"])
+def check(ctx: Context) -> None:
     """Check it all!"""
 
 

mkdocs.yml

@@ -71,6 +71,9 @@ extra_css:
 - css/material.css
 - css/mkdocstrings.css
 
+extra_javascript:
+- js/feedback.js
+
 markdown_extensions:
 - attr_list
 - admonition
@@ -146,3 +149,15 @@ extra:
     link: https://gitter.im/mkdocstrings/autorefs
   - icon: fontawesome/brands/python
     link: https://pypi.org/project/mkdocs-autorefs/
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: Let us know how we can improve this page.

pyproject.toml

@@ -57,7 +57,19 @@ version = {source = "scm"}
 [tool.pdm.build]
 package-dir = "src"
 editable-backend = "editables"
-source-includes = ["share"]
+excludes = ["**/.pytest_cache"]
+source-includes = [
+    "config",
+    "docs",
+    "scripts",
+    "share",
+    "tests",
+    "devdeps.txt",
+    "duties.py",
+    "mkdocs.yml",
+    "*.md",
+    "LICENSE",
+]
 
 [tool.pdm.build.wheel-data]
 data = [

scripts/make

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
 """Management commands."""
 
+from __future__ import annotations
+
 import os
 import shutil
 import subprocess
@@ -15,9 +17,12 @@ exe = ""
 prefix = ""
 
 
-def shell(cmd: str) -> None:
+def shell(cmd: str, capture_output: bool = False, **kwargs: Any) -> str | None:
     """Run a shell command."""
-    subprocess.run(cmd, shell=True, check=True)  # noqa: S602
+    if capture_output:
+        return subprocess.check_output(cmd, shell=True, text=True, **kwargs)  # noqa: S602
+    subprocess.run(cmd, shell=True, check=True, stderr=subprocess.STDOUT, **kwargs)  # noqa: S602
+    return None
 
 
 @contextmanager
@@ -37,8 +42,8 @@ def uv_install() -> None:
     uv_opts = ""
     if "UV_RESOLUTION" in os.environ:
         uv_opts = f"--resolution={os.getenv('UV_RESOLUTION')}"
-    cmd = f"uv pip compile {uv_opts} pyproject.toml devdeps.txt | uv pip install -r -"
-    shell(cmd)
+    requirements = shell(f"uv pip compile {uv_opts} pyproject.toml devdeps.txt", capture_output=True)
+    shell("uv pip install -r -", input=requirements, text=True)
     if "CI" not in os.environ:
         shell("uv pip install --no-deps -e .")
     else:
@@ -199,5 +204,7 @@ def main() -> int:
 if __name__ == "__main__":
     try:
         sys.exit(main())
-    except Exception:  # noqa: BLE001
-        sys.exit(1)
+    except subprocess.CalledProcessError as process:
+        if process.output:
+            print(process.output, file=sys.stderr)  # noqa: T201
+        sys.exit(process.returncode)