Trim anchors

[Blacksmoke16]

Currently when you permalink to a specific method within a type, the anchor includes the FQN of the type itself. Such that you end up with really long redundant URLs. E.g. https://athenaframework.org/Framework/Controller/ValueResolvers/RequestAttribute/#Athena::Framework::Controller::ValueResolvers::RequestAttribute#initialize.

Given the anchors are already isolated to the page itself, would it not be enough to just sub out the type name from the id of the method (and related types)? E.g. something like:

id=def.abs_id | replace("%s#" % obj.abs_id, '') | replace("%s." % obj.abs_id, '')

Where I updated the method to be referenced as def such that the type can still be accessed via obj.

[oprypin]

Given the anchors are already isolated to the page itself

They are not, though.. just that every user happens to use it this way

[oprypin]

Relevant ongoing work:

• feat: Add option to scan and register Markdown anchors autorefs#39

[pawamoy]

Yep, with the changes in the mentioned PR, it could be possible to change the anchor of objects while retaining the complete identifier for cross-refs.

[Blacksmoke16]

Gotcha, I guess I shall keep an eye on future releases then! Thanks!

[oprypin]

id=def.abs_id | replace("%s#" % obj.abs_id, '') | replace("%s." % obj.abs_id, '')

Hm so this is nice and all, but that makes it impossible to distinguish class methods and instance methods.

This would be some solution to distinguish them, although still looking rather weird:

• Foo/##bar vs
• Foo/#.bar

Because I think you're suggesting basically

• Foo/#bar vs
• Foo/#bar

[Blacksmoke16]

Easiest fix would be just do what the stdlib doc generator docs and do something like:

id=def.abs_id | replace("%s#" % obj.abs_id, 'instance-') | replace("%s." % obj.abs_id, 'class-')

Then you'd end up with Foo/#instance-bar and Foo/#class-bar which is probably good enough?

EDIT: Or add it at the end 🤷. Either or.

[oprypin]

@pawamoy
Oof this one may be harder than predicted

If I have a heading with this id:
Foo::Bar--usage-notes

Then I want this to remain the global identifier, but the actual local id to become:
usage-notes

So I need to suppress IdPrependingTreeprocessor but still somehow not suppress it for the purpose of making this the global identifier for autorefs.

[pawamoy]

I'm not sure to understand. IIUC, this is what we currently have:

• Foo::Bar docstring

Docstring summary.

## Usage notes

[Link to usage notes](#usage-notes).

• mkdocstrings will prefix ids and hrefs (as well as shift heading levels), so this becomes

<p>Docstring summary.</p>

<h4 id="Foo::Bar--usage-notes">Usage notes</h4>

<p><a href="#Foo::Bar--usage-notes">Link to usage notes</a></p>

• and then autorefs correctly registers Foo::Bar--usage-notes as identifier

[oprypin]

Right but the request is to have it become

<h4 id="usage-notes">Usage notes</h4>

but the need to have a globally linkable identifier still remains

[pawamoy]

I'm not sure a subheading (a heading in a docstring) can ever retain just its slug as id (usage-notes), because the shortest id we can give to its parent (the object using this docstring, Foo::Bar) is the last component of the object FQN (Bar), so the shortest id for a subheading would at least be prefixed with that name (Bar--usage-notes).

Unless we're documenting Foo::Bar on a page of its own? 🤔 Then there's no heading for the object itself, and its docstring headings stay the same. Hmmm.

[oprypin]

The parent's id is not so important, sure it needs to be at least Bar. But all its children don't need to contain even that.

The point that this issue is trying to make is that this is redundant:

/Foo/Bar/#Foo::Bar--usage-notes (subheading)

/Foo/Bar/#Foo::Bar.some_method (child)

[oprypin]

Yes the point is about the usage where the item is documented on its own on the page. As much as we say that it's not necessarily the case, I'm guessing 95%+ of usages are like that

[pawamoy]

Yeah, right. Then we must add aliases with FQN above headings, so that autorefs registers those and redirects to the headings with short ids. So I think the two mkdocstrings filters do_heading and do_convert_markdown must take an additional argument for the short name (in addition to the FQN). And this short name can probably be inferred from the current page's path (or somehow computed given some additional user configuration).

[oprypin]

There's also the really nasty case

/Foo/Bar/#Foo::Bar--usage-notes wants to become #usage-notes
but
/Foo/Bar/#Foo::Bar.some_method--usage-notes probably wants to become #some_method--usage-notes 😵‍💫 while still retaining the differently prefixed global identifier

[oprypin]

Alternatively we could say that people who are so certain about the page paths should just forfeit the autorefs syntax and use normal links (absolute links will work properly in the next mkdocs release)