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.14k stars 146 forks source link

Remove indentation in text template for markdown files #434

Closed pdashk closed 5 months ago

pdashk commented 11 months ago

Expected Behavior

Output of pdoc.Module().text() generates a markdown file where the headings are not indented. Indentation in markdown creates block quotes, which is not the intended purpose the the h3 (###) headings.

Example output:

`Structure(*args, **kwargs)`
:   Common class for all structures.

### Ancestors (in MRO)

* core.StructuredNode
* core.NodeBase
* properties.PropertyManager

Actual Behavior

text.mako template has indentations for these sections, such that output is:

Example output:

`Structure(*args, **kwargs)`
:   Common class for all structures.

    ### Ancestors (in MRO)

    * core.StructuredNode
    * core.NodeBase
    * properties.PropertyManager

Steps to Reproduce

Run pdoc -o in command line without --html flag to create `.md files.

Additional info

kernc commented 5 months ago

You need to enable Python-Markdown plugin def_list as we do: https://github.com/pdoc3/pdoc/blob/cf5bffdb89b32e060ff8dc08a6a78c7c4af67290/pdoc/html_helpers.py#L77

Thus:

$ markdown_py -x def_list -v <<'EOF' | tidy
`Structure(*args, **kwargs)`
:   Common class for all structures.

    ### Ancestors (in MRO)

    * core.StructuredNode
    * core.NodeBase
    * properties.PropertyManager
EOF
<dl>
    <dt><code>Structure(*args, **kwargs)</code></dt>
    <dd>
        <p>Common class for all structures.</p>
        <h3>Ancestors (in MRO)</h3>
        <ul>
            <li>core.StructuredNode</li>
            <li>core.NodeBase</li>
            <li>properties.PropertyManager</li>
        </ul>
    </dd>
</dl>

As you can see, h3 is nested (indented) inside dd.