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 <[email protected]>
<http://bugs.python.org/issue10716>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
