pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.12k stars 145 forks source link

anchor tags in markdown output are not being resolved #389

Open nestorSag opened 2 years ago

nestorSag commented 2 years ago

I'm not sure whether this is a bug or simply I'm missing some configuration option, but if its the latter I can't find it so I apologise. I'm using the --pdf option to get a markdown document, but every section in it seems to have the same anchor tag, namely 'id' , for example one of the headers in the produced file is:

Method fit_tail_model {#id}

where the tag should be something like package.module.class.fit_tail_model instead of id .

Expected Behavior

producing a markdown file where anchor tags are resolved so that reference within the same document work

Actual Behavior

All tags seem to be set to a default string of 'id', so module/class/method links don't work. Strangely, for html outputs this works fine.

Steps to Reproduce

  1. pdoc3 --pdf -c latex_math=True mymodule > docs.md

Additional info

LauraLMann commented 2 years ago

I think the problem is a typo in the pdf.mako file: <%def name="title(level, string, id=None)"> <% id = f' {{#id}}' if id is not None else '' %> ${('#' * level) + ' ' + string + id} </%def> The "id" after the # on the second line above should also be in {} (so there would be three sets of {} on that line). You can make this change in your own copy of pdf.mako, put your copy in a folder and run with it using: pdoc3 --pdf --template-dir . It worked for me.

nestorSag commented 2 years ago

That did the trick, thanks a lot!