Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bug: "regression" in 1.1.0 regarding "Multiple URLs found for" #52

Closed
llucax opened this issue Aug 21, 2024 · 24 comments
Closed

bug: "regression" in 1.1.0 regarding "Multiple URLs found for" #52

llucax opened this issue Aug 21, 2024 · 24 comments
Assignees

Comments

@llucax
Copy link

llucax commented Aug 21, 2024

Warning

This report might look like:

Workflow

After writing all of this, this probably should have been a feature request instead...

TL;DR: Could an option be added to disable the "Multiple URLs found for" warning and just let references to silently resolve locally as before and/or have an option to resolve links with multiple URLs found to a specific page?

Description of the bug

After doing an update from 1.0.1 to 1.1.0 I started to get many warnings in the form:

Multiple URLs found for 'x.y.z': ['reference/x/y/z/#x.y.z', 'user-guide/x/y/z#x.y.z']. Make sure to use unique headings, identifiers, or Markdown anchors (see our docs).

And since we are using strict mode, this means an error and docs that won't build.

To Reproduce

The thing is we are using this pattern to try to have as much documentation as possible as part of docstrings, but still have a nice and more organized "user guide": we use some internal modules docstrings as the user guide section and then include it in the markdown documentation. For example:

$ cat docs/user-guide/formula-engine.md
# Formula Engine

::: frequenz.sdk.timeseries.formula_engine.FormulaEngine
    options:
        members: None
        show_bases: false
        show_root_full_path: false
        show_source: false

::: frequenz.sdk.timeseries.formula_engine.FormulaEngine3Phase
    options:
        members: None
        show_bases: false
        show_root_full_path: false
        show_source: false

And we also generate API reference documentation using some script based on what's suggested in the docs, which will create a file like:

$ cat docs/reference/frequenz/sdk/timeseries/formula_engine/index.md 
::: frequenz.sdk.timeseries.formula_engine

Hence, we have the same anchor in 2 different pages.

Expected behavior

Before this upgrade all worked as more or less fine, links just being resolved locally when possible, and externally when not.

But I think things could be even improved for this use case, as before in the example above FormulaEngine in the user guide will resolve to the user guide, but ideally it should resolve to the API reference.

  1. Add an option to ignore multiple URLs for warnings.

    a. Globally in mkdocs.yaml
    b. Locally in the `:: x.y.z`` block

    Example:

    # Formula Engine
    
    ::: frequenz.sdk.timeseries.formula_engine.FormulaEngine
        options:
            members: None
            show_bases: false
            show_root_full_path: false
            show_source: false
            disable_multiple_urls_warning: true
  2. A way to tell where to resolve multiple references to a specific page. For example:

    For example something like:

    # Formula Engine
    
    ::: frequenz.sdk.timeseries.formula_engine.FormulaEngine
        options:
            members: None
            show_bases: false
            show_root_full_path: false
            show_source: false
            resolve_multiple_urls:
                "frequenz.sdk.timeseries.formula_engine.FormulaEngine": reference/frequenz/sdk/timeseries/formula_engine.md

Additional context

@pawamoy
Copy link
Member

pawamoy commented Aug 21, 2024

Thanks for the report! I was expecting to get one but still thought this warning had to be enabled by default. I definitely didn't anticipate this use-case you have though.

But I think things could be even improved for this use case, as before in the example above FormulaEngine in the user guide will resolve to the user guide, but ideally it should resolve to the API reference.

That's exactly the issue the warning is aiming to solve. With non-unique heading ids across pages, cross-references might link you to one or the other, non-deterministically (or deterministically, but depending on the order the pages are built, and this might be more complex than that).

I agree that this could be a feature request indeed: the feature I think we need here is a way to change the heading ids of the ones if your Guide pages. By the way, I can't seem to find any mkdocstrings-generated headings in your Guide pages, could you link me to some examples? I'd like to see how you render them. EDIT: I see subheadings such as #frequenz.sdk.actor--the-run-function, but not headings themselves. EDIT 2: OK I see #frequenz.sdk.timeseries.formula_engine.FormulaEngine. Well, since there isn't even a signature rendered, I believe the manual heading approach below would work for you? Even if you rendered a signature I think it would work.

It might be possible to workaround this right now, by doing the following:

  • manually write the headings in your guide pages: ### MyClass
  • but change their id: ### MyClass {#guide-MyClass} or ### MyClass {#guide-complete.path.to.MyClass}
  • render the object by omitting its heading:
    ::: complete.path.to.MyClass
        options:
            show_root_heading: false

We have to change the Guide headings because we cannot change the API ones (yet), as that would break cross-site references. Maybe not afternall. Will need to think about it.

@llucax
Copy link
Author

llucax commented Aug 21, 2024

By the way, I can't seem to find any mkdocstrings-generated headings in your Guide pages

Sorry, I don't know what this means. 😞, so I don't know how to point you to examples. Not sure if you still need them given the EDITs.

It might be possible to workaround this right now, by doing the following:
...
Maybe not afternall. Will need to think about it.

Yeah, no, sadly it doesn't. We are even using show_root_heading: false already in some places where we get warnings too.

@pawamoy
Copy link
Member

pawamoy commented Aug 21, 2024

@llucax I'd like to inspect a bit more your docs sources, is there a particular branch I should look at? One that triggers the warnings. I can't seem to find the sources for https://frequenz-floss.github.io/frequenz-sdk-python/v1.0-pre/user-guide/formula-engine/. I don't think the gen-files script generates that too, right?

@llucax
Copy link
Author

llucax commented Aug 21, 2024

The default branch should have the issue. We just pinned the dependency to avoid CI failures until we can find a solution, but if you manually update the dependency it should break.

All non-generated docs are in docs/. The doc you are looking for is here: https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/docs/user-guide/formula-engine.md.

https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/docs/user-guide/microgrid-concepts.md also have the issue.

Thanks a lot for looking at it! ❤️

@pawamoy
Copy link
Member

pawamoy commented Aug 23, 2024

Thanks, I wasn't looking into the right repo.

So, by adding the following options:

        show_root_heading: false
        show_root_toc_entry: false

(which you already have in actors and microgrid-concepts)

...that reduces the number of warnings. The four remaining ones come from subheadings in the corresponding objects' docstrings (### The run() Function): these subheadings are rendered and their id is prefixed with the object path, whether we've rendered the root heading or not, so whether we're in the guide or the reference. In the end: duplicated ids.

A few solutions that come to mind:

  • (in mkdocstrings) detect that the root heading (and toc entry) are not rendered, and therefore avoid prefixing the subheadings. But the issue would pop its head again with more than two places where we render the docstring.
  • (in mkdocstrings) add an option to configure the prefixing behavior for subheadings: no prefix, default behavior (prefix with object path), custom prefix. We do something similar in Markdown Exec 👍

Obviously, we could also consider reverting, and putting these warnings behind an option. But that means a lot of maintenance, to maintain incorrect/un-deterministic behavior a few projects rely on. If many projects are impacted by this and come here to add their voice, we'll do something, but for now it seems only two projects are impacted.

WDYT? Would an option to configure (sub)headings prefixes work for you? I imagine something like this:

# Actors

::: frequenz.sdk.actor
    options:
        members: []
        headings_prefix: ""
        show_bases: false
        show_root_heading: false
        show_root_toc_entry: false
        show_source: false

There's an alternative solution by the way. You could use pymdownx.snippets instead of mkdocstrings to inject your docstrings into your "Guide" Markdown pages. See https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippet-sections. Snippets lets you declare sections in your sources, whathever the language (and comment syntax). Then you can inject just these sections into pages.

In src/frequenz/sdk/actor/__init__.py:

# License: MIT
# Copyright © 2022 Frequenz Energy-as-a-Service GmbH

# Please note this docstring is included in the getting started documentation in docs/.
"""Actors are a primitive unit of computation that runs autonomously.

<!-- --8<-- [start:docstring] -->

## Actor Programming Model
...

<!-- --8<-- [end:docstring] -->
"""

I'm using HTML comment syntax since we're in a Markdown docstring. Note that the docstring summary is not included in the snippet section because it would be weird. So here you'd have to repeat just this summary in the Markdown page:

# Actors

Actors are a primitive unit of computation that runs autonomously.

--8<-- "src/frequenz/sdk/actors/__init__.py:docstring"

Well, it's not perfect, just wanted to list this alternative 🙂

@llucax
Copy link
Author

llucax commented Aug 23, 2024

Hi, thanks again for having a deep look at this. I also agree that just disabling the warning is not ideal, as there is a potential issue, it would be much better to have a way to disambiguate something ambiguous instead.

About the snippets solution, I prefer to avoid it, another goal of us is to keep docstrings as readable as possible, same reason we try to keep most docs in docstrings, they are accessible via the IDE and code editors, which is in our experience the main way our users look at docs.

So your proposed solution of headings_prefix means that these headings will get a different prefix depending on where they were "included", so for example we could leave no prefix for the reference docs and have a headings_prefix: "user-guide" in the user guide for example? I guess that could work.

So we are currently linking to that "The run() method" using:

[_run]: #the-_run-method

In this case, if we leave the link as is it will point to the reference, and if we change it to user-guide-the-_run_method it will point to the user guide, right?

I guess we can live with that, but ideally the link should resolve "locally" when possible, it would be best if it resolved to the user guide when rendered in the user guide and to the reference when rendered in the reference.

This is why I was thinking if it would be possible to have some sort of "resolve multiple URL using this page" kind of option I suggested before. So in this case mkdocstrings will find 2 locations for #the-_run-method, but we'll have something like this:

::: frequenz.sdk.timeseries.formula_engine.FormulaEngine
    options:
        members: None
        show_bases: false
        show_root_full_path: false
        show_source: false
        resolve_multiple_urls:
            "#the-_run-method": reference/frequenz/sdk/actor.md

So it will use the link to that page without giving any warnings.

I can imagine it might be a bit of work and maybe it is not justified if we one of a kind using this documentation scheme, but it would be good to know if that would be even doable :)

@pawamoy
Copy link
Member

pawamoy commented Aug 23, 2024

About the snippets solution, I prefer to avoid it, another goal of us is to keep docstrings as readable as possible

Completely agree 👍

so for example we could leave no prefix for the reference docs and have a headings_prefix: "user-guide" in the user guide for example?

That's the idea 🙂

In this case, if we leave the link as is it will point to the reference, and if we change it to user-guide-the-_run_method it will point to the user guide, right?

Yes!

ideally the link should resolve "locally" when possible, it would be best if it resolved to the user guide when rendered in the user guide and to the reference when rendered in the reference.

Then you shouldn't use autorefs for this. Autorefs will always resolve references to one and only one location, be it on the same page or somewhere else. Instead, you should use the native reference syntax [some title](#some-anchor-on-this-very-page): this will always be local to the page, wherever the docstring is rendered.

[...] I can imagine it might be a bit of work and maybe it is not justified [...]

Such a solution would have to be implemented in autorefs, but would only be supported through mkdocstrings, which would be a bit weird. Autorefs will definitely have more features in the future (and this might be one), but we're not ready for that yet. We need solid foundations for this type of features first (there's some work going in that direction with #46) 🙂

@pawamoy
Copy link
Member

pawamoy commented Aug 23, 2024

Actually, even prefixing ids might be complicated to implement 🤔 If the-run-method gets prefixed as user-guide-the-run-method, then what are we supposed to do with [the run() method][the-run-method]? Should we prefix the id there too? But we don't know yet that user-guide-the-run-method exists. And even if it does, how do we know we don't really want to use the-run-method untouched, because it could exist somewhere else later? 🤔 🤔 🤔

@llucax
Copy link
Author

llucax commented Aug 23, 2024

Then you shouldn't use autorefs for this. Autorefs will always resolve references to one and only one location, be it on the same page or somewhere else. Instead, you should use the native reference syntax [some title](#some-anchor-on-this-very-page): this will always be local to the page, wherever the docstring is rendered.

I see, so if all the anchors pointing to symbols are fixed by using:

        show_root_heading: false
        show_root_toc_entry: false

(not sure if the later is desirable or not, will need to check it out)

And for regular anchors we can avoid autorefs and it does exactly what we want (resolve locally) without any warnings, I think that's all we need. I'm not sure why we used autorefs there, but I wouldn't surprised if it was just a mistake.

I will try it out.

Actually, even prefixing ids might be complicated to implement 🤔 If the-run-method gets prefixed as user-guide-the-run-method, then what are we supposed to do with [the run() method][the-run-method]? Should we prefix the id there too? But we don't know yet that user-guide-the-run-method exists. And even if it does, how do we know we don't really want to use the-run-method untouched, because it could exist somewhere else later? 🤔 🤔 🤔

If the above works out, then I don't think I need prefixes at all. I'm not sure if we are using deep linking to link into a section of a docstring, but if we do I guess we could live without those.

Will try to give this a try (next week) and report back.

Once again, thanks a lot for your support! ❤️

@pawamoy
Copy link
Member

pawamoy commented Aug 23, 2024

I'm not sure why we used autorefs there, but I wouldn't surprised if it was just a mistake.

Possibly for consistency. For example, the Actor class also uses an autorefs link to the-_run-method IIRC.

It's possible that there are places where you cannot use a "local reference" (direct link using # instead of autorefs) because the link is not rendered on the same page, and using an autoref will emit warnings. So you might find yourself stuck again 😕

If the above works out, then I don't think I need prefixes at all.

Yes please, don't hesitate to share your progress with me, I'll gladly chime in again and try to help 😄 I'll leave this open in the meantime.

@llucax
Copy link
Author

llucax commented Aug 26, 2024

OK, I'm having a look at this and now I know why we used the [the run() method][_run] format, this was just to have shorter links I think, and to only having to care about slugification in one place. I'm not sure if it is 100% standard markdown, but it seems most parsers accepts [text][ref] as a link and then you can declare the link later like [ref]: https://mylink.com. We are using it like that, so the intention was not to use autorefs for this link, just to make it more concise and avoid duplication.

So in this case the intention here was to explicitly define the link, which happens to point to a HTML fragment/ID instead of a full URL.

Is there any way for autorefs to detect when we are actually explicitly defining where [ref] points to in [text][ref]?

On the other hand, we do are using some autoref links for "deep linking" into some other sections:

This doesn't seem to be fixed by just adding:

        show_root_heading: false
        show_root_toc_entry: false

(these options are actually already there)

For this former we could get around with removing the --frequenz-sdk-microgrid-model and just linking to the whole module, that seems to work, but in the actor it would really hurt the cross-linking in the docs.

So it seems all our problems are not solved by the solution above, and some are only partially solved, producing worse quality docs (less precise linking).

I'll await in case you have any new ideas, and otherwise I guess we'll have to link to modules instead of module's sections and just tell the user "go find this section inside that doc yourself" basically, which I guess it kind of goes against the goals of this tool (to make the best docs ever possible :) ).

I created a draft PR with my attempt to solve this:

I would be awesome if the last 2 commits 2 commits prior to the last one were not necessary somehow...

ml-evs added a commit to Materials-Consortia/optimade-python-tools that referenced this issue Aug 26, 2024
@pawamoy
Copy link
Member

pawamoy commented Aug 26, 2024

Is there any way for autorefs to detect when we are actually explicitly defining where [ref] points to in [text][ref]?
I would be awesome if the last 2 commits 2 commits prior to the last one were not necessary somehow...

Good news, commit b0996a3 shouldn't be necessary. Bad news, I'm not sure why links weren't rendered naturally. Let me explain.

autorefs only tries to fix references that weren't already rendered naturally. All these [`_run()`][_run] should be rendered naturally without autorefs because you define [_run]: #the-_run-method later in the document. When these references do not work through mkdocstrings, it's usually because the docstring uses sections (parameters, note, whatever), which means the docstring is split in different sections which have to be converted independently, which means that [`_run()`][_run] and [_run]: #the-_run-method get separated. But in your case, I don't see any sections: you're using plain markup, so the whole docstring should be rendered in one go, and these links should be rendered, and autorefs should never have to fix them later 🤔 I'll investigate.

Second commit is what I expected, unfortunately. Generally speaking, rendering the same contents in two different places, and the same autorefs linking to this contents twice too, makes it impossible to not get the warnings. Well at least autorefs is not equipped to deal with this. The only way to fix this would be to update the link syntax to be able to provide additional metadata to help decide how to resolve the link (in addition to a way of specifying id prefixes, as previously discussed).

@pawamoy
Copy link
Member

pawamoy commented Aug 26, 2024

Another option, probably much more attainable in the short term, would be to add an option to mkdocstrings to say "don't register any heading generated here against autorefs", similarly to mkdocstrings/mkdocstrings#671 and mkdocstrings/mkdocstrings#672.

EDIT: Well it seems it's covered by mkdocstrings/mkdocstrings#671 already. But maybe both aspects (autorefs and inventory) should be made configurable distinctly.

@pawamoy
Copy link
Member

pawamoy commented Aug 26, 2024

I tried again in your repo, and the _run links are correctly rendered. I don't see any change in your PR that would prevent them for working. Maybe you confused warnings somehow?

@pawamoy
Copy link
Member

pawamoy commented Aug 26, 2024

With or without this commit, I only get three seemingly unrelated warnings (that I cannot trace to their origin, but it's another story). EDIT: OK it's because I had the previous code still installed in the venv. No warnings now, even with commit b0996a3 reverted.

ml-evs added a commit to Materials-Consortia/optimade-python-tools that referenced this issue Aug 26, 2024
* Bump the python-dependencies group with 3 updates

Bumps the python-dependencies group with 3 updates: [fastapi](https://github.com/fastapi/fastapi), [jarvis-tools](https://github.com/usnistgov/jarvis) and [mkdocs-material](https://github.com/squidfunk/mkdocs-material).


Updates `fastapi` from 0.112.1 to 0.112.2
- [Release notes](https://github.com/fastapi/fastapi/releases)
- [Commits](fastapi/fastapi@0.112.1...0.112.2)

Updates `jarvis-tools` from 2024.5.10 to 2024.8.10
- [Release notes](https://github.com/usnistgov/jarvis/releases)
- [Commits](https://github.com/usnistgov/jarvis/commits)

Updates `mkdocs-material` from 9.5.31 to 9.5.33
- [Release notes](https://github.com/squidfunk/mkdocs-material/releases)
- [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG)
- [Commits](squidfunk/mkdocs-material@9.5.31...9.5.33)

---
updated-dependencies:
- dependency-name: fastapi
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: python-dependencies
- dependency-name: jarvis-tools
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-dependencies
- dependency-name: mkdocs-material
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: python-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>

* Pin mkdocs-autoref for now (see mkdocstrings/autorefs#52)

* s/autoref/autorefs/g

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Matthew Evans <git@ml-evs.science>
@pawamoy
Copy link
Member

pawamoy commented Aug 26, 2024

A lot was written here, let me try to summarize.

  • Unless a lot of projects show that they are impacted, we won't revert this to put the warnings behind an option as it means a lot of maintenance.
  • Supporting the use-case where the same headings and autorefs are added more than once to the site by juggling with link syntax, id prefixing, and other shenanigans, seems a lost cause.
  • For this reason @llucax's initial suggestion of resolving links "locally" seems appealing again. While it wouldn't work in all cases, we could alleviate warnings with an option to say "resolve to the URL that most closely matches the current page". Example: if we're in page user-guide/actors/ and we have two URLs for identifier the-run-method which are reference/sdk/etc/#actor--the-run-method and user-guide/actors/#actor--the-run-method, use the second one and don't emit a warning. If we're in page /something/else/entirely, none of the two URLs remotely matches, so we emit a warning. Here, "matching" URLs would mean "start with the same thing". We could set this option to true by default (bringing us back closer to previous state, but providing a bit more correct link resolution), and allow users to set it to false for even stricter checks.
  • An additional option in mkdocstrings could prevent registering heading ids against autorefs, to keep only one true location for headings (or reducing the number of valid, linkable locations).

WDYT?

@llucax
Copy link
Author

llucax commented Aug 28, 2024

Thanks for the summary, I was a bit busy and didn't have time to go through all of it properly.

The last 2 points sound very reasonable to me, and it seems like they should cover all our use-cases. The "local resolution" seem like the most important to me, it should bring us on par to what we had before.

The second one would be a nice add-on, and I think it could actually improve our current documentation, as we could avoid adding some undesirable self-references in the user guide and just always point the users to the reference.

I will update the draft PR to remove the unnecessary commit when I have some time. Thanks for checking that!

@pawamoy
Copy link
Member

pawamoy commented Aug 29, 2024

Not really relevant, but there's another change coming up that can potentially make CI fail, see our announcement here: #56. Users who saw their CI fail because of the duplicated headings warnings and who pinned mkdocs-autorefs to avoid latest version might want to wait or test the upcoming version before unpinning/upgrading 🙂 I'll let you know when the change is merged, and again when it is released.

@llucax
Copy link
Author

llucax commented Aug 29, 2024

Thanks for the heads up, I think (and hope!) we will not be impacted by that one.

I updated my draft PR and I can confirm that the changes to [run()][_run] were not necessary. 👍

@llucax
Copy link
Author

llucax commented Aug 29, 2024

Do you have any ideas of a time frame for implementing the local references, if you plan to do it eventually at all? Just to know if I should wait for a solution or if I should merge that PR as it and live with the "degraded" documentation for now.

@pawamoy
Copy link
Member

pawamoy commented Aug 29, 2024

I'm currently focusing on mkdocs-autorefs so these changes and features will be released in the upcoming week(s).

pawamoy added a commit that referenced this issue Sep 1, 2024
@pawamoy
Copy link
Member

pawamoy commented Sep 1, 2024

OK, just pushed the "resolve closest" feature commit. The option is false by default, because I don't want to encourage its use, since it can be problematic for object inventories.

plugins:
- autorefs:
    resolve_closest: true

See https://github.com/mkdocstrings/autorefs?tab=readme-ov-file#non-unique-headings.

Just waiting to see how CI behaves, and I'll publish a new release 🙂

@pawamoy pawamoy closed this as completed Sep 1, 2024
@pawamoy pawamoy removed the unconfirmed This bug was not reproduced yet label Sep 1, 2024
@llucax
Copy link
Author

llucax commented Sep 2, 2024

I updated the PR and using the new option worked flawlessly! Also no regressions detected with 1.2.0 🎉

Thanks a lot for taking care of this ❤️

github-merge-queue bot pushed a commit to frequenz-floss/frequenz-sdk-python that referenced this issue Sep 2, 2024
This PR unpins the `mkdocs-autorefs` plugin, so we can use the latest
version, but to do that we need to make some changes to the way we link
to sections in the docs.

The new version produces warnings when there are more than one possible
URL to resolve an "autoref" link, and since we have strict more enabled,
the docs fail to build if we have any warnings.

The simplest way to avoid the warning in some cases is just adding the
following options:

```
  show_root_heading: false
  show_root_toc_entry: false
```

This avoids anchors being created in the user guide, so it removes the
ambiguity of the link.

To remove some other warnings we add a new `autorefs` plugin option to
`resolve_closest`, which allows to resolve the reference to the "closest
URL". See the documentation for more information:
https://github.com/mkdocstrings/autorefs#non-unique-headings.

This PR was done following suggestions in:

* mkdocstrings/autorefs#52
github-merge-queue bot pushed a commit to frequenz-floss/frequenz-sdk-python that referenced this issue Sep 2, 2024
This PR unpins the `mkdocs-autorefs` plugin, so we can use the latest
version, but to do that we need to make some changes to the way we link
to sections in the docs.

The new version produces warnings when there are more than one possible
URL to resolve an "autoref" link, and since we have strict more enabled,
the docs fail to build if we have any warnings.

The simplest way to avoid the warning in some cases is just adding the
following options:

```
  show_root_heading: false
  show_root_toc_entry: false
```

This avoids anchors being created in the user guide, so it removes the
ambiguity of the link.

To remove some other warnings we add a new `autorefs` plugin option to
`resolve_closest`, which allows to resolve the reference to the "closest
URL". See the documentation for more information:
https://github.com/mkdocstrings/autorefs#non-unique-headings.

This PR was done following suggestions in:

* mkdocstrings/autorefs#52
@pawamoy
Copy link
Member

pawamoy commented Sep 2, 2024

Great! Thanks for your help and patience!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants