put source code below docstring

Problem Description

When browsing documentation, the source code details are hidden and docstring appears in its natural place, right below the function definition … until you click the “view source” option. After clicking that option, source code appears between function definition and docstring … so docstring gets displaced down many lines (as many as the code length). So all the rich docstring format and all links it might contain disappear from our scope (until we close the source code).

1. Default view:

<div class="attr function">...</div>     <details> <summary>View Source</summary>
<div class="codehilite"></div></details>   <---- HIDDEN STUFF
<div class="docstring">...</div>   <----   possible links to other modules and functions

1. Click “view source”

<div class="attr function">...</div>     <details> <summary>View Source</summary>
    <div class="codehilite">
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    </div>
</details>
<div class="docstring">...</div>   <----   Hey!!!  I was at top but I am here now. Move up & down to read me if you want.

Proposal

In my opinion, it might be much better to keep docstring below function definition, and put source code below docstring. So we can still see the nice docstring in its original place, and use the links to other functions and modules without having to move down.

<div class="attr function">...</div>
<div class="docstring">...</div>   <----   Don't worry. I am still here and will always be.
<details>
    <summary>View Source</summary>
    <div class="codehilite">
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    ...
    </div>
</details>

Alternatives

Can I configure this using templates? Anyway, I think the default look would improve with this change.

[mhils]

Yes, exactly. You can find some more resources on how templates work at https://pdoc.dev/docs/pdoc.html#editing-pdocs-html-template and https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.

[mhils]

huge characters because you forgot to escape <h1> in this function???

pdoc does not escape HTML tags in docstrings, this is expected behavior. pdoc.markdown2 is a vendored copy of the markdown2 library, which for practical reasons is included without any modifications (even if it’s somewhat ugly).

To appreciate its usefulness, you’ll have to pdocument a long and wide function (with many too-wide or very-indented lines of code), and see how it looks like with default pdoc css (unreadable right side of text).

I’m perfectly aware of the current layout. It will stay this way. pdoc displays a bit above 100 characters per line without scrolling. For reference, black has a maximum line length of 88 characters^1. It is very easy to scroll horizontally on all modern desktop OS and mobile devices. Yes, this is opinionated, but please accept that I’m not going to discuss it any further.