This is a straight-forward project.

Pydoc currently generated 1990's style html which mixes content and presentation, making it very difficult for users to customize the appearance of the output.

It is full of html like:

<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
<tr bgcolor="%s">
<td valign=bottom>&nbsp;<br>
<font color="%s" face="helvetica, arial">&nbsp;<br>%s</font></td
><td align=right valign=bottom
><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
    ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')

    def section(self, title, fgcol, bgcol, contents, width=6,
                prelude='', marginalia=None, gap='&nbsp;'):
        """Format a section with a heading."""
        if marginalia is None:
            marginalia = '<tt>' + '&nbsp;' * width + '</tt>'
        result = '''<p>
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="%s">
<td colspan=3 valign=bottom>&nbsp;<br>
<font color="%s" face="helvetica, arial">%s</font></td></tr>
    ''' % (bgcol, fgcol, title)
        if prelude:
            result = result + '''
<tr bgcolor="%s"><td rowspan=2>%s</td>
<td colspan=2>%s</td></tr>
<tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)

Please convert it to simple, validated HTML with the formatting moved to a simple, validated default style sheet.  Liberally apply div/span elements with class/id attributes as necessary.

I believe Ron has done something along these lines already.  See issue2001.  Committed css file is empty, (see r86971) but I am adding Ron to "nosy" in case he has something in the pipeline.

See also the calendar module for an example of a "modern" html.

I uploaded the css file I used in an experimental version of pydoc.  It may give some useful starting values. 

Before this is done, the old server code should be removed (also for 3.3). (another issue?)  There are two files in the tools/scripts directory that may need attention as well. pydocgui.pyw and pydoc3.

Those two scripts are just three-liners pydoc launchers.

I disagree about the CSS reset.  Default values and user-set values have a reason for being there, and I share the viewpoint that they should not be reset.

I'm looking for a deeper fix, all the in-line styling replaced by a stylesheet.  Can you guys work together on bring this to fruition?

Eric, most of what's in that file is what I figured out by trial and error in order to get it to work on the different browsers at that time. (about 3 years ago.)  You are probably more experienced with css than I am, so you are more than welcome to update and change anything in there. :-)

What do you think about starting with a set of static html pages to get the css and html to work nice, and then only after that is done, edit pydoc to generate those pages.  That should get us mostly there, and simplify what needs to be done in pydoc.

A good procedure is to start afresh with an empty, embedded style sheet and replace the html styling attributes one at a time, while keeping the overall look and feel the same.   At the end of the process the embedded style sheet can be converted to external.

I think that's how I ended up with the style sheet I uploaded.  It works, but it can be a slow process.

Another factor is the pydoc server will reread an external style sheet on browser refreshes. So you can see the results of style sheet changes without restarting pydoc. If it's embedded, you need to edit the program and restart everything each time.

I was thinking that I may still be able to make a set of static html files that go along with that style sheet.  Then we can adjust the css class names and make other changes, then use that as a guide for replacing the html.

Eric, what do you think?

The uploaded stylestyle is *much* bigger than I expected.  There should be no more than a one-to-one correspondence.  With inheritance, perhaps even fewer entries.

Ok, I just looked at them again, I didn't remember how different it was.  They probably won't be much help other than maybe seeing how some things could be done. Here's a zip file of some saved pages, so you can take a look.

The CSS also has a validation error, some warnings and could be written better IMHO (specifically I don't like the placement of the {}).

I also don't believe that extensive CSS resets are useful -- they usually just lead to lot of redefining. I usually limit myself to * { margin: 0; padding: 0; } and possibly specify specific values when necessary. Minor differences with different browsers can be perfectly fine in lot of cases.

[Raymond]
> I'm looking for a deeper fix, all the in-line styling replaced by a
> stylesheet.  Can you guys work together on bring this to fruition?
When I talked about the CSS reset, I was referring to a precise part of the file proposed by Ron, so we’re already discussing together :-)

I wonder how desirable it is to preserve the look and feel of the pages.  We all agree on externalizing the CSS and add a way for the users to add their own stylesheet; why not take the opportunity to also improve the style?  Huge blocks of colors are not that attractive to me :)

Regarding workflow, I’d find easier to start from bare HTML that works nice (yes, I test with w3m) and then add style.  Technically, I’d like to maintain the HTML as a small set of files (in pydoc_data) containing fragments of HTML with placeholders ({} or $): That’s easy to edit, to validate (a very simple script can put the fragments together) and to use.

I agree that the CSS file should be as short as possible (in content), but not too short (in file size).  For example, trailing commas in properties and brackets on their own line will allow nice diffs, just like Python.

(I won’t have much time for Python in December, but we have a lot of time before 3.3b1 :)

There's no rush on this one.
There desired properties are:
* separate content from presentation
* validated CSS and HTML
* simple CSS so that people can *easily* customize it
* possibly offer two premade stylesheets
  1) a default beautiful one
  2) one the closely approximates the current look and feel

If the current look cannot be recreated, it should be taken as a sign that the content/presentation split wasn't done well.

Here is a tentative start on this.  (css_v1.diff)

The css file is much better.  It's shorter, simpler and validated.

The header and navbar panel use it in the new server.

Added a markup call to the topic page contents.  (The same markup call is already used for the doc strings.)

Extra items in the css are what I come up with from testing different ways of doing things.

The HtmlDoc class has methods that take colors. Can this be changed or does it need to be depreciated first? 

    def heading(self, title, fgcol, bgcol, extras=''):
        """Format a page heading."""
        return '''
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
<tr bgcolor="%s">
<td valign=bottom>&nbsp;<br>
<font color="%s" face="helvetica, arial">&nbsp;<br>%s</font></td
><td align=right valign=bottom
><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
    ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')

For the interactive server, I can override these methods with no problem, but the generated docs won't benefit from this until the HtmlDoc class is replaced.  Any suggestions?

Well, you could reuse these arguments to mean CSS classes, and have styles like ".red { color: red }" :)

It may be useful to change those to 'id=' and 'class=' if possible.

It isn't clear to me how much of pydoc is still part of the public api in python 3.x.  pydoc.__all__ is set only to ['help'].  

Entering help(pydoc) just gives the basic help and command line arguments along with.

DATA
    __all__ = ['help']
    help = <pydoc.Helper instance>

There is nothing in the official (online) docs on importing pydoc or any of it's classes or methods.  

But dir(pydoc) shows all the methods, and the HTMLDoc class is still importable even though they aren't listed in __all__.

Here is a new diff which updates all the new pydoc pages to use the css file. 

The css file is simpler and cleaner.  I also made a few adjustments to the url handler error handling, and changed the titles in the head sections so they say "Pydoc" instead of "Python" as they are PyDoc pages about Python.

None of these changes effect any of the old pydoc code yet.  This is about as far as we can go without removing the old tk panel and server.

Time for some feed back.  And how close do we really need it to be to the original?

:-)

A few comments about css_v2.diff:
1) when the value is '0', there's no need to specify the unit (e.g. 0em);
2) when the color is specified the background-color should be specified as well (and vice versa);
3) hex colors (e.g. #00FF00) should be preferred to named colors (e.g. gray);
4) some selectors and properties don't work with older browsers (e.g. E > F or min-width);
5) there are a few empty dl.*{} that I would remove (unless you plan to fill them later);
6) the style I prefer for CSS is:
selector {
  property: value;
}

Regarding the HTML:
1) using an HTML 4.01 strict doctype would be better;
2) all the style-related attributes and elements should be removed (e.g bgcolor, valign, <font>);
3) using .red { color: red; } is not a good idea. Classes' names should describe the role of the element (e.g. header, entry) and not their style (otherwise when you want to change the page with a blue theme you'll end up with a .red { color: blue; }). If the colors are passed directly to the HTML they should be removed and left to the CSS(s) only. I don't know the code well enough to say if this is doable and/or if it requires a deprecation first;
4) the <li>s in html_header() should be closed, same for all the other elements that support a closing tag, even if optional (e.g. <dt>, <dd>);

There are also some minor incontinences in the indentantion, e.g.:
+        link_list = ['<a href="%s.html">%s</a>' % (name, name)
+                    for name in sys.builtin_module_names
+                    if name != '__main__']
+        contents = [html.index_columns('Built-in modules',
+                    link_list, css_class='section modules')]
+        link_list = ['<a href="%s.html">%s</a>' % (name, name)
+                      for name in sorted(Helper.keywords.keys())]
(the "contents" one is indented correctly), and some extra space after the '('.

> If the colors are passed directly to the HTML they should be
> removed >and left to the CSS(s) only. I don't know the code
> well enough to say if this is doable and/or if it requires a
> deprecation first;

We may have to do dome depreciating when it comes to the old HTMLDoc class methods.  Would it be possible to depreciate the whole class instead of the separate methods?  If so, it would be good if we can squeeze that into 3.2. <hint hint>  Or else we may not be able to finish this until Python 3.4.

The empty css elements will be used later.

Here is the css_v3.diff for review.  I'd like to hear any thoughts about the general html structure and class/id names.

Beside validating them, I test with firefox and chromium. I don't have easy access to ms-explorer or the current mac browser.

These arguments should not really be of concern.  If we indeed deem them public API, they can stay but be ignored.

To go forward I can create a new private api instead of changing HTMLDoc, that would be preferable.

Should the -w option also use the new html pages?  Or do we need a new option for that?

A reminder: Check for instances where html.escape is not called on data inserted into the html pages.

I'll update the patch as the non-css (error handling) parts made it into python 3.2.  :-)

I added a few comments for ccs_v3.diff on rietveld.

I would like to take on this issue if, as it seems, Ron is no longer working on it. I'm thinking of using HTML5 and maybe replicating the default output of Sphinx.

Using an HTML5 doctype is ok, but I'm not sure it's a good idea to use new HTML5 elements/features yet (those shouldn't be necessary anyway, so basically you should end up with valid HTML 4 strict with an HTML5 doctype).

I'm going to go over this issue again with fresh eyes after having been away for some time.

Recent experience with another project has helped answer some of the questions I had earlier.  Particulary, how not to over specifying class names and id's.  This should lead to cleaner html pages that will be easier to style with css.  It should also lead to a smaller patch. ;-)

It seems that most of the input so far has more to do with spelling rather than function.  Is there a prefered style guide for css that we should use?

> Is there a prefered style guide for css that we should use?

If you mean indentation/spacing, my preferred style is:

selector {
    property1: value1;
    property2: value2;
    ...
}

FWIW I agree an HTML5 doctype should be used.