separate CSS file for the generated docs

[mfrigerio17]

Problem Description

All the generated HTML files embed a large, yet single-line, CSS sheet. Also, it appears to be the same across all the html files.
Besides this being unnecessary duplication (I think), it prevents the user from playing around with the CSS rules to change the look of the docs. This is useful to try out the changes before possibly changing the pdoc template for the CSS.

Proposal

It would be nice if the CSS sheet was generated as a separate file, and simply included in the html docs.
It would be tidy if also the syntax-highlighting-CSS was generated separately, next to the main one.

---

BTW: Thanks for working on pdoc! I was happy to see that the project is back

[mfrigerio17]

Perhaps this section of the docs is related to my request (?)

[mhils]

All the generated HTML files embed a large, yet single-line, CSS sheet. Also, it appears to be the same across all the html files.

Yes, this is correct. The main reason for bundling everything into standalone HTML files is that it makes pages load very fast as no additional HTTP roundtrips need to be made to load subresources. The file size increase is negligible here, all CSS (Bootstrap Reboot + pygments + pdoc) is only about 14kb combined right now. Second, as you already mentioned the way the CSS is part of the HTML template right now makes it easy to embed pdoc into other systems.

it prevents the user from playing around with the CSS rules to change the look of the docs.

If you want to play around with CSS rules, I'd recommend to write a custom template like this:

module.html.jinja2

{% extends "default/module.html.jinja2" %}
{% block style_content %}
    {{ super() }}
    body {
      background-color: red !important;
    }
{% endblock %}

and then run pdoc's web server using pdoc -t . <your-module>. Then you can edit the CSS and just reload the page. https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/module.html.jinja2 may be helpful to explore the default style. :)

Does that make sense?

[mfrigerio17]

Hi, thanks for the prompt reply.

Does that make sense?

Kind of :)

Now I understand Jinja template inheritance, and I see what you mean. However, that allows me to generate additional CSS rules, not to have the default CSS generated separately so that I can change its entries.

But anyway, I see you have reasons to do it as it is.

The file size increase is negligible here [..]

But is the speed increase, on the other hand, not negligible?

In any case, I know that to do what I want I could also work on custom templates, have a new one for the CSS sheet and modify the html one to generate a <link rel="stylesheet"> ....
I was originally wondering whether it would be better for pdoc itself to do it like that.

(The original reason I started looking into this, was the spacing between classes/methods, which I do not like; the docs here look better than what I get from pdoc by default, where there is no clear separation (bigger margin) between classes)

[mhils]

But is the speed increase, on the other hand, not negligible?

Inlining styles (and all other subresources) means one client<->server roundtrip less, which can make a noticeable difference in the long tail. It's significant enough that HTTP/2 Push Promises were invented as a mitigation technique, but arguably not significant enough for them to actually reach adoption. :) We are admittedly arguing on a very high standard here, pdoc documentation is much faster than most websites anyhow.

If you feel that a slightly larger margin between classes would look better, please feel free to send a PR - I'm open to small cosmetic improvements if they don't add significant complexity. :)

[mfrigerio17]

Just some thoughts:

Classes and methods get the same top margin as they both have the attr CSS-class, thus they get equally spaced (vertically).

Perhaps classes (or module members more in general) could use more top margin than members within a class, to visually reflect the containment (yes, I saw that you also have the classattr CSS class).

I noticed that this "issue" is accidentally (?) solved by the View source button, which has negative margin and messes things up.

See here an html generated with --no-show-source (the top-margin of the method is respected (and equal to the class top-margin)):

As opposed to this one, where the CSS margin-collapse with a negative margin makes it look different

(look at the Attachable class to notice the difference, as the yellow and purple strips make it harder)

Anyway, what looks good/bad is subjective, but maybe the change in the case of view-source was not intended.

Not a big deal though.

[mhils]

view-source indeed shouldn't change the spacing. If you have layout improvements/fixes please do send a PR, I'm happy to take a closer look! :)

[abubelinha]

modify the html one to generate a <link rel="stylesheet"> ....

Thanks @mfrigerio17 for opening this issue. Your suggestion solved my use case:

I share a bunch of python scripts in different machines. One of them is pretty old and I cannot install any recent web browser; so pdoc html output is not readable (every module page content occupies the whole page width, so about leftmost 30% of content underlays below left index).

Probably this is not the best way, but I solved that by applying the following css rule to <main> tag in module.html.jinja2:

main.pdoc { left:30%; width:70%; position:relative; }

I put that in an external CSS file which is only present in the old machine (so my "normal" machines don't load those rules).

• Doing it this way, the same documentation is now browsable and readable in both old and new machines.
• Otherwise, I would have had to create and maintain different copies of the whole documentation.

I think this technique would also allow users of a package's documentation to easily personalize its look (i.e. font sizes, dark themes and things like that).
So thanks again @mfrigerio17 for your good advice.
And thanks again @mhils for your good and so configurable package.

@abubelinha