Repository navigation
Modernize pydoc to use better HTML and separate CSS #54925
Description
| BPO | 10716 |
|---|---|
| Nosy | @birkenfeld, @rhettinger, @terryjreedy, @abalkin, @aroberge, @ezio-melotti, @merwok, @bitdancer, @ambv, @berkerpeksag, @serhiy-storchaka, @tritium21, @JulienPalard, @Mariatta, @tirkarthi, @brickman1444 |
| PRs | |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2010-12-16.09:25:37.954>
labels = ['type-feature', 'library', '3.11']
title = 'Modernize pydoc to use better HTML and separate CSS'
updated_at = <Date 2021-10-09.07:36:58.565>
user = 'https://github.com/rhettinger'bugs.python.org fields:
activity = <Date 2021-10-09.07:36:58.565>
actor = 'mdk'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2010-12-16.09:25:37.954>
creator = 'rhettinger'
dependencies = []
files = ['20216', '20236', '48230', '48231']
hgrepos = []
issue_num = 10716
keywords = ['patch']
message_count = 57.0
messages = ['124119', '124144', '124147', '124157', '124158', '124159', '124162', '124164', '124176', '124177', '124179', '124181', '124195', '124306', '124825', '124857', '124858', '124863', '125033', '125049', '125111', '125113', '125122', '127542', '130629', '165401', '165406', '183304', '183319', '234936', '234940', '234941', '234942', '236962', '246917', '246920', '277934', '278084', '278089', '278090', '278098', '278119', '278123', '278126', '278127', '278166', '278191', '338700', '338703', '338716', '338717', '397265', '397353', '397354', '402962', '403397', '403520']
nosy_count = 21.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'belopolsky', 'ron_adam', 'donmez', 'aroberge', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'PeterLovett', 'lukasz.langa', 'berker.peksag', 'serhiy.storchaka', 'tritium', 'azsorkin', 'Fr\xc3\xa9d\xc3\xa9ric Jolliton', 'mdk', 'Mariatta', 'xtreak', 'brickman1444']
pr_nums = ['28651']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue10716'
versions = ['Python 3.11']
Activity
rhettinger commentedon Dec 16, 2010
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> <br>
<font color="%s" face="helvetica, arial"> <br>%s</font></td
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.
abalkin commentedon Dec 16, 2010
I believe Ron has done something along these lines already. See bpo-2001. Committed css file is empty, (see r86971) but I am adding Ron to "nosy" in case he has something in the pipeline.
abalkin commentedon Dec 16, 2010
See also the calendar module for an example of a "modern" html.
ronadam commentedon Dec 16, 2010
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.
merwok commentedon Dec 16, 2010
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.
rhettinger commentedon Dec 16, 2010
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?
ronadam commentedon Dec 16, 2010
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.
rhettinger commentedon Dec 16, 2010
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.
ronadam commentedon Dec 17, 2010
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?
rhettinger commentedon Dec 17, 2010
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.
ronadam commentedon Dec 17, 2010
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.
ezio-melotti commentedon Dec 17, 2010
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.
44 remaining items
rhettinger commentedon Mar 23, 2019
I've found the HTML to be useful (-w mode, not running a server) for generating quick documentation (much lighter weight commitment than using sphinx). I show this in my intro classes and the engineers are usually impressed with it.
This is really easy and requires neither configuration files or reST markup:
$ python -m pydoc -w statistics wrote statistics.htmlSo, my vote it to keep it.
I would still like modern HTML 5 with CSS however.
aroberge commentedon Mar 23, 2019
On Sat, Mar 23, 2019 at 6:27 PM Raymond Hettinger <report@bugs.python.org>
wrote:
I submitted code to do this in January 2015 on the bug tracker but, except
for some interest by a single person, my submission was essentially
ignored. I do not claim it is perfect, but I thought it was a significant
improvement as it did use HTML 5 with CSS.
André Roberge
tirkarthi commentedon Mar 24, 2019
I stumbled upon this issue because I think this is a potential improvement. One of the reasons I don't use it is due to the outdated UI but since it also generates HTML doc for installed packages in a virtual environment I find this to be a useful feature like rdoc (ruby), rustdoc (rust) and are actively maintained helping documentation of third party packages too for local reference.
I have less knowledge about CSS but I tried updating css_v3.diff with master and added boostrap.css from CDN to pydoc which adds spacing along with improving layout and font. Attached is a screenshot that is looks better with the CSS patch and bootstrap. Including bootstrap is not lightweight option in the Python distribution but can be seen as a proof of improvement.
tirkarthi commentedon Mar 24, 2019
Thanks @aroberge for the patch and your efforts on improving it https://aroberge.blogspot.com/2015/01/scratching-itch-improving-pydoc.html
brickman1444 commentedon Jul 11, 2021
Hey all, I'd like to note my interest in this issue getting addressed. I have a use case where I'd like to generate documentation for a module and using non-core modules to do that requires some approval that I would like to avoid.
I understand there are other more important issues but this issue has had a patch waiting for review for ten years. Can we move this forward somehow?
merwok commentedon Jul 12, 2021
Someone would need to take the patch, apply it to current main branch, fix issues and open a PR.
merwok commentedon Jul 12, 2021
On second thought, this issue is not purely programming, but also has a UI component. Better HTML and separated CSS would be good, but before that I think we’d need someone with design chops to mock up a better page layout and style (better than big coloured rectangles!), then I think have a discussion on python-dev (not to discuss all details in committee, but to validate the overall change).
JulienPalard commentedon Sep 30, 2021
Tried myself at it.
I'm not a front-end guy, fasten your seatbelts.
I tried to keep it minimal, but after some work the change is not that small, I focused on the HTML modernization only, not the design (to try to land at least a first step toward modernization).
JulienPalard commentedon Oct 7, 2021
Does someone want to review #28651?
JulienPalard commentedon Oct 9, 2021
New changeset c91b6f5 by Julien Palard in branch 'main':
bpo-10716: Migrating pydoc to html5. (GH-28651)
c91b6f5
furkanonder commentedon May 11, 2023
@JulienPalard The issue seems to have been solved. I think we can issue the problem.