search

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

How to switch from Markdown Extra to other Markdown flavors? #269

Open f0ff886f opened 3 years ago

f0ff886f commented 3 years ago

Expected Behavior

I'd like my module docs to be rendered correctly in something like a GitHub README.md file. Problems are caused with Markdown Extra, I'd like to switch to something simpler.

Actual Behavior

The use of Markdown Extra (and specifically things like definition lists) cause Class methods (or all Class documentation, really) to render as one giant codeblock.

Steps to Reproduce

  1. pdoc foo.py where foo.py is https://gist.github.com/f0ff886f/99f504e700d2fc0ec9e3a8012d2fa3f9
  2. Output is: https://gist.github.com/f0ff886f/dab4023f59eb54ad7e97b7b983d981e1

Additional info

kernc commented 3 years ago

pdoc foo uses somewhat undocumented text.mako template, which you can edit/override per your preference.

This is primarily a documentation bug.

f0ff886f commented 3 years ago

Ah I see, so we can just create a whole new template to fit whatever style of Markdown we wish. Cool, I will try to make something visually appealing and share it back.

dleske commented 3 years ago

@f0ff886f Glad you created this issue--it enabled me to find half an answer to my problem (generating API documentation automatically for my git repo).

Now for the other half ;) -- did you ever create such a template?

Cool, I will try to make something visually appealing and share it back.

dleske commented 3 years ago

I've been munging the text template for my own uses but can't get past the fact that the markdown-generating code produces non-markdown output:

Returns
-----=
Integer job identifier.

Raises
-----=
...

This isn't interpreted by MD renderers I'm aware of. Looking at the code in html_helpers.py (whose functions appear to be used by non-HTML rendering) there's a comment about this being done to avoid re-interpretation by numpy docstring parsing, but I haven't yet figured out a way around this in my use of to_markdown() from my template.

Suggestions welcome, not sure where I'm going wrong.

dleske commented 3 years ago

Created a text template for my use and possibly others can make use of it too.