Modernize pydoc to use CSS

[ezio.melotti]

http://bugs.python.org/review/10716/diff/1852/3477
File Lib/pydoc.py (right):

http://bugs.python.org/review/10716/diff/1852/3477#newcode2506
Lib/pydoc.py:2506: items = items,
The spaces around the = can go.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2508
Lib/pydoc.py:2508: )
The ) should be closed on the previous line.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2514
Lib/pydoc.py:2514: '  </dd>'
It's better to add a \n at the end of the line or use a triple quoted string
(possibly with redent()) to preserve proper indentation in the output.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2515
Lib/pydoc.py:2515: )
The ) should be closed on the previous line.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2521
Lib/pydoc.py:2521: css_class="index-columns")
css_class should be indented under title.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2525
Lib/pydoc.py:2525: )
See previous comments about \n and the ).

http://bugs.python.org/review/10716/diff/1852/3477#newcode2536
Lib/pydoc.py:2536: return template.format(css_class=css_class, section=section)
See previous comments.
Also this function is very similar to index_columns. Maybe it's better to have a
single function that accepts another css_class that is either 'index-lines' or
'index-columns'. (Of course this can't be done if they are part of the public
API)

http://bugs.python.org/review/10716/diff/1852/3477#newcode2551
Lib/pydoc.py:2551: Python {version} - [{build}, {compiler}, {platform}]
</p>

http://bugs.python.org/review/10716/diff/1852/3477#newcode2593
Lib/pydoc.py:2593: '{name}</a>')
I don't like too much the fact that the packages have a <span class="package">
whereas the modules have an <a class="module">. Maybe using a span for modules
too or include "(package)" in the link (and the remove the span) would be
better.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2598
Lib/pydoc.py:2598: content =''.join(contents)
Missing space after the =.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2606
Lib/pydoc.py:2606: )
\n and ).
There are also other occurrences later.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2635
Lib/pydoc.py:2635: title = 'getfile %s' % path.replace('%20', ' ')
urllib.unquote()?

http://bugs.python.org/review/10716/diff/1852/3477#newcode2694
Lib/pydoc.py:2694: )
I use either:
values = dict(foo=bar,
              baz=asd)
or:
values = dict(
    foo=bar,
    baz=asd,
)

http://bugs.python.org/review/10716/diff/1852/3477#newcode2710
Lib/pydoc.py:2710: err = str(exc),
You can remove the spaces around the =, if you want to keep it they should be
added to the previous "values" dict too.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2718
Lib/pydoc.py:2718: '      <p>{err}'
It's always better to close the </p>, even if it's not mandatory. (You can also
have more <dd> after a <dt>, I don't know if it makes sense here though.)

http://bugs.python.org/review/10716/diff/1852/3476
File Lib/pydoc_data/_pydoc.css (right):

http://bugs.python.org/review/10716/diff/1852/3476#newcode24
Lib/pydoc_data/_pydoc.css:24: #page{padding: 1em;}
#page { padding: 1em; }

http://bugs.python.org/review/10716/diff/1852/3476#newcode32
Lib/pydoc_data/_pydoc.css:32: #page-title{
#page-title {

http://bugs.python.org/review/10716/diff/1852/3476#newcode33
Lib/pydoc_data/_pydoc.css:33: display: inline-block;
Are all these inline-block really necessary?

http://bugs.python.org/review/10716/diff/1852/3476#newcode167
Lib/pydoc_data/_pydoc.css:167: text-indent: -8ex;
Why you switched to ex here?

[eric.araujo]

http://bugs.python.org/review/10716/diff/1852/3477
File Lib/pydoc.py (right):

http://bugs.python.org/review/10716/diff/1852/3477#newcode2508
Lib/pydoc.py:2508: )
> The ) should be closed on the previous line.

That’s done on purpose by Ron so that any future addition only adds one line in
the diff.  I like this style.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2593
Lib/pydoc.py:2593: '{name}</a>')
Why don’t you like it?

http://bugs.python.org/review/10716/diff/1852/3477#newcode2694
Lib/pydoc.py:2694: )
I don’t see why you said that: The code uses the second style you describe.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2710
Lib/pydoc.py:2710: err = str(exc),
This contradicts a previous comment you made :)  Except for some special cases,
I find the rule in PEP 8 (no spaces around = in function calls) good.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2718
Lib/pydoc.py:2718: '      <p>{err}'
I agree, it’s more readable to close elements.

http://bugs.python.org/review/10716/diff/1852/3476
File Lib/pydoc_data/_pydoc.css (right):

http://bugs.python.org/review/10716/diff/1852/3476#newcode124
Lib/pydoc_data/_pydoc.css:124: dl.module{}                     /* These are not
used yet. */
Then better not to include them.

http://bugs.python.org/review/10716/diff/1852/3476#newcode226
Lib/pydoc_data/_pydoc.css:226: background-color: #f4f4ff;  /* Shows white space.
*/
Nitpick: whitespace*

http://bugs.python.org/review/10716/diff/1852/3478
File Lib/test/test_pydoc.py (right):

http://bugs.python.org/review/10716/diff/1852/3478#newcode431
Lib/test/test_pydoc.py:431: ("", "PyDoc: Index of Modules"),
We already talked about that, but I really prefer Pydoc to PyDoc.

[ezio.melotti]

http://bugs.python.org/review/10716/diff/1852/3477
File Lib/pydoc.py (right):

http://bugs.python.org/review/10716/diff/1852/3477#newcode2508
Lib/pydoc.py:2508: )
On 2011/03/11 23:35:54, eric.araujo wrote:
> > The ) should be closed on the previous line.
> 
> That’s done on purpose by Ron so that any future addition only adds one line
in
> the diff.  I like this style.

I don't think having one more line is a big deal.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2593
Lib/pydoc.py:2593: '{name}</a>')
On 2011/03/11 23:35:54, eric.araujo wrote:
> Why don’t you like it?

Because it's not symmetric, if I want to parse the HTML to get a list of the
packages/modules I'd have to search for two different elements rather that get
them all at once and distinguish them with the class.  Anyway it's not a big
deal since no one will probably parse this.

http://bugs.python.org/review/10716/diff/1852/3477#newcode2694
Lib/pydoc.py:2694: )
On 2011/03/11 23:35:54, eric.araujo wrote:
> I don’t see why you said that: The code uses the second style you describe.

In the second style the ) is closed under the 'v' of values, similarly to what
you would do in C, e.g.:
if (cond) {
    content here;
}

http://bugs.python.org/review/10716/diff/1852/3477#newcode2710
Lib/pydoc.py:2710: err = str(exc),
On 2011/03/11 23:35:54, eric.araujo wrote:
> This contradicts a previous comment you made :)  Except for some special
cases,
> I find the rule in PEP 8 (no spaces around = in function calls) good.

I don't use spaces myself, but it's ok for me if someone prefers to use them in
this case (when there's only a key/value pair per line).  Spaces or not, the
style should be consistent.

http://bugs.python.org/review/10716/diff/1852/3476
File Lib/pydoc_data/_pydoc.css (right):

http://bugs.python.org/review/10716/diff/1852/3476#newcode124
Lib/pydoc_data/_pydoc.css:124: dl.module{}                     /* These are not
used yet. */
On 2011/03/11 23:35:54, eric.araujo wrote:
> Then better not to include them.

According to msg125111 they will be used later.

http://bugs.python.org/review/10716/diff/1852/3478
File Lib/test/test_pydoc.py (right):

http://bugs.python.org/review/10716/diff/1852/3478#newcode424
Lib/test/test_pydoc.py:424: self.assertRaises(ValueError, f, "", "foobar")
These might be better written like:
with self.assertRaises(ValueError):
    pydoc._url_handler('', '')
with self.assertRaises(ValueError):
    pydoc._url_handler('', 'foobar')

[eric.araujo]

>> That’s done on purpose by Ron so that any future addition only adds
>> one line in the diff.  I like this style.
> I don't think having one more line is a big deal.

It’s certainly not a big deal, just a style thing and a minor nicety.

>> I don’t see why you said that: The code uses the second style you
>> describe.
> In the second style the ) is closed under the 'v' of values,

Oh, I didn’t catch that.  I agree with you it’s nicer.

>> This contradicts a previous comment you made :)  [...]
> [...] Spaces or not, the style should be consistent.

What I was saying :)

>>> These are not used yet. */
>> Then better not to include them. 
> According to msg125111 they will be used later.

Fine.

> These might be better written like:
> with self.assertRaises(ValueError):
>     pydoc._url_handler('', '')

My preferred style too.