[issue10716] Modernize pydoc to use better HTML and separate CSS

[Frédéric Jolliton]

Frédéric Jolliton added the comment:

Oh god. The HTML produced by pydoc is awful.

This is absolutely nothing modern about it.

The code itself hurts my brain. It feels very old (14 years old..), and the HTML production is overly complex, and hard to check regarding correct quoting/escaping.

Generating modern HTML5/CSS would mean:

 - Using <h1>, <h2>, for section title,
 - Forget about <br> (this element should never be used nowadays),
 - Forget about <hr> (let the CSS decide when to insert a visual separator after/before a given element),
 - Don't use <code> for block of code. This is an inline element. Use <pre class="code"> for example.
 - Don't use <table> all over the place for formatting everything (use <li> for the list of modules for instance),
 - Drop these useless <dd></dd> (empty!)
 - No need to replace \n by <br>, or to replace space by  . The formatting can be achieved by white-space: pre in CSS.
 - <a name=".."> or <a id=".."> could be replaced by <span id=".." class=".."> to distinguish them from hyperlinks.
 - the table "docclass" could be a serie of <h2> (or <h3>) title followed by the content of the section. The table seems useless because there are no particular requirement for an alignment.
 - and so on, and so on, ..

Actually, I think this need a complete rewrite.

This is a useful tool to have included with Python, but this need a serious refresh.

To me, a "modern" documentation is something like this (from the Rust documentation):

    https://doc.rust-lang.org/std/option/enum.Option.html
    https://doc.rust-lang.org/std/option/index.html

(Look at the generated HTML too. It's rather straightforward.)

----------
nosy: +Frédéric Jolliton

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10716>
_______________________________________