ENH: Configurable highlight style

[KyleKing]

Fixes #34

---

I'd be happy to undo any (hopefully not all 😄 ) of these changes, so let me know if you want to implement 1, 3, and 5 but not 2 and 4, etc. The four main changes are listed below and shown in side-by-side screenshot comparisons below:

1. Implement Atom One Light Highlight.js style (other alternatives could be Foundation, Github Gist, A 11 Y Light, or others from https://highlightjs.org/static/demo/). This directly addresses #34
2. Preserve newlines from source code docstrings with white-space: pre-wrap;. At work, we have a compact docstring style where the newlines need to be preserved in the documentation. See discussion from pdoc: pdoc/179#comment. I think keeping the newlines is more consistent with how the comments were written in a text editor, but I'm open to dropping this change
3. Highlight the entire click region for SOURCE CODE with the same background color as the hljs style (and add a small amount of padding) (background-color: #fafafa; /* Match HLJS backgd */)
4. Shrink the code text to 12px so it fits more compactly for easier review
5. Remove the blue selection box when clicking the SOURCE CODE element (outline: none !important;)

Screenshots

Each example shows all of the proposed changes, but I call-out specific changes for each example. Generated with:

1. pip install beautifulsoup4
2. pdoc bs4 --http localhost:8000

Example 1

Proposed

Current

Notes

2 - Examples 1 and 2 show how the pre-wrap change comes into play causing the newlines from the source code to be preserved

5 - Because of cursor: pointer;, when you click SOURCE CODE, the browser will momentary highlight the div. In the proposed version, outline: none !important; prevents the blue highlight from appearing on click (focus)

Example 2

Proposed

Current

Notes

2 - See how the pre-wrap change comes into play causing the newlines from the source code to be preserved (decode() and handle_starttag())

3 - The clickable region for source code is lightly highlighted

Example 3

Proposed

Current

Notes

1,4 - The source code variable and built-ins are more clearly highlighted and the code better fits within the height-limited section

[kernc]

1. Implement Atom One Light Highlight.js style (other alternatives could be Foundation, Github Gist, A 11 Y Light, or others from https://highlightjs.org/static/demo/). This directly addresses #34

Bikeshedding. Imho #34 (comment) is a better way to address #34.

2. Preserve newlines from source code docstrings with white-space: pre-wrap;. At work, we have a compact docstring style where the newlines need to be preserved in the documentation. See discussion from pdoc: pdoc/179#comment. I think keeping the newlines is more consistent with how the comments were written in a text editor, but I'm open to dropping this change

I'd prefer to drop it too. If you need this at work, you can use a custom head.mako file with contents such as:

<style>
  dd p {
    white-space: pre-wrap;
  }
</style>

3. Highlight the entire click region for SOURCE CODE with the same background color as the hljs style (and add a small amount of padding) (background-color: #fafafa; /* Match HLJS backgd */)

I'm ok with this, but only when the details are expanded (open), i.e. on:

.source details[open] summary { background: ... }

4. Shrink the code text to 12px so it fits more compactly for easier review

👍

5. Remove the blue selection box when clicking the SOURCE CODE element (outline: none !important;)

The blue box is compliments of your chosen OS / widget toolkit. For me, the outline is far less conspicuous. See also: http://www.outlinenone.com. You can override CSS without overriding the rest of the HTML template by using the mentioned head.mako file.

[KyleKing]

Thanks for the feedback. I dropped 2,3,5 and kept 4 (12 px code).
I pushed new changes to support an hljs_stylename in config.mako that keeps github as the default. Let me know if you like that change

Diff: https://github.com/pdoc3/pdoc/pull/38/files

[KyleKing]

I made the changes!

[kernc]

Thanks!