How to switch from Markdown Extra to other Markdown flavors?

[f0ff886f]

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

• pdoc version: 0.9.1

[kernc]

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

This is primarily a documentation bug.

[f0ff886f]

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]

@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]

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]

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