Incorrect URL fragments in docstrings of objects with identical headers

[JCGoran]

Problem Description

The URL fragments (stuff after # in the URL) in docstrings which have an identical section header are always linked to the same anchor.

Steps to reproduce the behavior:

An example is probably best here:

# example.py

def f1():
    """
    Examples
    --------
    Something
    """

def f2():
    """
    Examples
    --------
    Something else
    """

Build the docs using:

pdoc --docformat numpy example.py

When viewing the docs in a browser, we get this (I am using the Display #Anchors extension to make it visible):

Note that both Examples anchors lead to the same URL fragment, namely, example.html#examples, so it is basically impossible to create an external link to a given section of a docstring of an object if the same module has multiple objects with the same header name.

A possible solution would be to just prepend the full name of the object (in this case, example.html#f1-examples and example.html#f2-examples). Note the hyphen between the object and the header name, this is necessary to disambiguate from an identical object called f1_examples (since a hyphen is not allowed anywhere when naming a Python object).

System Information

pdoc: 13.1.0
Python: 3.11.2
Platform: Linux-6.1.0-5-amd64-x86_64-with-glibc2.36

[mhils]

This sounds like a duplicate of #497? :)

[JCGoran]

This sounds like a duplicate of #497? :)

Indeed it does! I'm not seeing any issues upstream though, should I open one? Also, regarding your fix in #497 (comment), I can't really get it to work, would you mind providing a more "complete" example (assuming it still works)?

[mhils]

I'm not seeing any issues upstream though, should I open one?

Please feel free to either raise an issue or ideally submit a PR. :)

would you mind providing a more "complete" example (assuming it still works)?

Something like this (completely untested):

#!/usr/bin/env python3
from pathlib import Path
import pdoc
import pdoc.render_helpers

if __name__ == "__main__":
    pdoc.render_helpers.markdown_extensions.pop("header-ids")
    pdoc.pdoc("foo", output_directory=Path("./out"))