search

mitmproxy / pdoc

API Documentation for Python Projects
https://pdoc.dev
MIT No Attribution
1.93k stars 189 forks source link

Customize level of headings that are wrapped in anchor links? #725

Open adigitoleo opened 1 month ago

adigitoleo commented 1 month ago

Problem Description

Currently, pdoc renders markdown headings within docstrings (e.g. ### Heading) into HTML heading elements (e.g. h3). However, it is not possible to link to specific headings within a docstring because they are not wrapped in an <a>anchor</a> element.

My intended use case is to be able to reference specific headings in a module-level docstring (or in __init__.py), in the same way that I am able to reference class and function definitions in the API docs.

Proposal

Wrap rendered headings within docstrings in HTML anchor elements.

Alternatives

I guess the alternative is to manually maintain a TOC at the top of the docstring to at least give a quick visual overview.

adigitoleo commented 1 month ago

Oops, I think I'm being silly. There do seem to be anchor links in the published version of our docs, but not when I preview the live version on localhost. Is that intended? I'll check on another browser to be sure...

adigitoleo commented 1 month ago

OH ok, it only adds anchor links for h1 and h2. That seems sensible. Am I missing that in the pdoc docs somewhere? Or should it be added?

Feel free to close.

mhils commented 1 month ago

I don't think it's in the docs, but happy to merge a PR that adds it to the "header-ids" bullet in https://pdoc.dev/docs/pdoc.html#markdown-support! :)

adigitoleo commented 1 month ago

happy to merge a PR

Can do, I just want to clarify that markdown2 doesn't support customizing which heading level is the cutoff. That seems to be the case, am I right?

mhils commented 1 month ago

I don't know, this should be in the markdown2 docs. :)

On Fri, 9 Aug 2024, 16:17 Leon, @.***> wrote:

happy to merge a PR

Can do, I just want to clarify that markdown2 doesn't support customizing which heading level is the cutoff. That seems to be the case, am I right?

— Reply to this email directly, view it on GitHub https://github.com/mitmproxy/pdoc/issues/725#issuecomment-2278054114, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHY2PTDVRFA4LLCQ6QYZLTZQTFQ3AVCNFSM6AAAAABMIOKDX2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENZYGA2TIMJRGQ . You are receiving this because you commented.Message ID: @.***>

adigitoleo commented 1 month ago

Hmm, can't see anything. I think the part of markdown2 responsible for this is the "header ids" extra, which only has a brief wiki entry here. Nothing about h2 being the maximum. I tried searching in the 4k line markdown2 implementation for "header-ids" but couldn't work out where this limitation is coming from... In any case maybe the correct place to document this is in the header-ids wiki entry (that pdoc already links to) but I'd have to ask over there to find out what is going on.