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

[Julien Palard]

Julien Palard  added the comment:


New changeset c91b6f57f3f75b482e4a9d30ad2afe37892a8ceb by Julien Palard in 
branch 'main':
bpo-10716: Migrating pydoc to html5. (GH-28651)
https://github.com/python/cpython/commit/c91b6f57f3f75b482e4a9d30ad2afe37892a8ceb


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Víctor Terrón]

Change by Víctor Terrón :


--
nosy:  -vterron

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Julien Palard]

Julien Palard  added the comment:

Does someone want to review https://github.com/python/cpython/pull/28651?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Julien Palard]

Julien Palard  added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Julien Palard]

Change by Julien Palard :


--
pull_requests: +27019
pull_request: https://github.com/python/cpython/pull/28651

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo  added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo  added the comment:

Someone would need to take the patch, apply it to current main branch, fix 
issues and open a PR.

--
versions: +Python 3.11 -Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Zac Gross]

Zac Gross  added the comment:

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?

--
nosy: +brickman1444

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

Thanks @aroberge for the patch and your efforts on improving it 
https://aroberge.blogspot.com/2015/01/scratching-itch-improving-pydoc.html

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


Added file: https://bugs.python.org/file48231/Screen Shot 2019-03-24 at 
10.58.33 am.png

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

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.

--
keywords: +patch
nosy: +mdk
Added file: https://bugs.python.org/file48230/css_master.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Andre Roberge]

Andre Roberge  added the comment:

On Sat, Mar 23, 2019 at 6:27 PM Raymond Hettinger 
wrote:

>
> Raymond Hettinger  added the comment:
>
> 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.html
>
> So, my vote it to keep it.
>
> I would still like modern HTML 5 with CSS however.
>

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

>
> --
>
> ___
> Python tracker 
> 
> ___
>

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.html

So, my vote it to keep it.

I would still like modern HTML 5 with CSS however.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +xtreak

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Change by Raymond Hettinger :


--
versions: +Python 3.8 -Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray added the comment:

My memory of the thread (I haven't gone back and checked) was that the thought 
was to drop html output altogether because the sphinx docs were more useful for 
anyone wanting to use html, and network connectivity was so universal in this 
day and age that having a local html server for offline uses was of minimal 
utility.

So your vote that it be kept because it is useful to idle and can be made more 
useful by improving the html seems to me to decide the issue in favor of making 
the improvements (given someone willing to do the patch review and any 
additional needed coding).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

Since David added me as nosy, I will address the IDLE issues raised above.

But first, a question.  Does 'deprecating HTML output' merely mean deprecating 
the old output in favor of new and better HTML output, or deprecating having 
any html output, which would also mean deprecating the html doc server?  I am 
strongly against the latter.

Currently, IDLE, in both pyshell and run.py, imports pydoc and sets 
"pydoc.pager = pydoc.plainpager".  Bypassing pydoc.getpager this way is not 
documented, but seems perhaps necessary.  Other than this, I believe 
'help(xyz)' is treated by IDLE just like any other user code.

Serhiy, msg278126 > "It would be nice if IDLE use this feature"

There are actually two features: hmtl output, and the html server, which uses 
the default browser to display the output.

Since a year ago, IDLE help displays the html IDLE doc produced by sphinx in a 
subclass of tkinter Text that feeds the page to a subclass of HTMLParser.  The 
code is in help.py.  Sphinx's html seems to follow Frédéric's guidelines in 
msg246917.  I suspect the CSS files are ignored.  We might want to do something 
similar with pydocs html output.

Raymond: is sphinx's pydoctheme anything like the css you are looking for?  
Could it be used as a starting point?
  
  


There have been requests that 'long' help output (for modules and classes) be 
displayed separately from Shell itself so that it does not obscure history and 
be easier to refer to.  If we do this, using html instead of plain text would 
be nice, especially if new features were added.

Serhiy, cont. > "I think we should enhance HTML output not just by making it 
looking better, but by adding more interactivity. For example add the ability 
to collapse classes, methods, etc, add more hyperlinks."

I mainly use pydoc server for tkinter.  I would *love* have the repetitive 
'inherited methods' section for each class collapsed by default.  Ditto for 
when I use help interactively.  To me, this is the single worst feature of 
pydoc output.

David msg278127 > "If Terry would like to see pydoc enhanced to support idle, 
then I think that would decide the issue."

I am not sure what you mean by 'the issue' and I can't currently think of 
anything IDLE-specific that pydoc should do, other than be consistent.  
However, producing modern, decent looking html output would make html use 
possible.  Incorporating the current output, as displayed in the server, might 
be a net negative PR move.


Side note: thinking about how to make a clickable link in a Text widget, I 
realized that that IDLE already does some syntax tagging for colors (keywords, 
builtins, def and class identifiers).  The same tags could be bound to 
double-click or right-click to display help popups, such as
--
The "if" statement is used for conditional execution:

   if_stmt ::= "if" expression ":" suite
   ( "elif" expression ":" suite )*
   ["else" ":" suite]

It selects exactly one of the suites by evaluating the expressions one
by one until one is found to be true (see section Boolean operations
for the definition of true and false); then that suite is executed
(and no other part of the "if" statement is executed or evaluated).
If all expressions are false, the suite of the "else" clause, if
present, is executed.

Related help topics: TRUTHVALUE

with the grammar chunk highlighted and the related topics clickable.  What IDLE 
would need here is consistency in the format of the help texts.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray added the comment:

That sounds like a reasonable argument to me.

To clarify something in my last post: 5 should be skipped in terms of opening 
new issues because it is already covered by this issue.

If Terry would like to see pydoc enhanced to support idle, then I think that 
would decide the issue.

--
assignee: eric.araujo -> 
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

I disagree with deprecating HTML output. Pydoc has builtin HTTP server, it 
provides the documentation with hyperlinks. It would be nice if IDLE use this 
feature for displaying interactive help.

I think we should enhance HTML output not just by making it looking better, but 
by adding more interactivity. For example add the ability to collapse classes, 
methods, etc, add more hyperlinks.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray added the comment:

You sound like you think we want to get rid of pydoc, which is certainly not 
true :).  As I understand it it is only the *html* output of pydoc that we are 
considering deprecating.

Yes, you should open separate issues for your proposed changes.  1 and 2 should 
be separate issues, 3 and 4 should be combined into a proposal to convert pydoc 
to using argparse.  5 you can skip, and 6 I don't think will be accepted, 
although you are welcome to propose it along with some motivating use cases.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Peter Lovett]

Peter Lovett added the comment:

I see that pydoc still useful, and have 6 points I'd like to work on with 
pydoc. Is this too much for one issue? Should I break bits out to another 
issue(s)? Although it would make sense to do it all in one go.

---
Pydoc is a good way to get users (especially beginners) used to writing 
docstrings, and leads nicely into doctest and similar tools.
Other languages, such as Perl and Java have similar tools that generate text or 
html documentation from code.
Some have used pydoc classes for their own uses.
It is not intended that pydoc would compete with Sphinx. Sphinx is not core.

pydoc changes
---
1. Fix .\ (or ./) problem
Currently, documenting a single module requires the prefix of .\
TODO: Change to check:
If it's a directory, document all .py files in that directory.
If it's a Python file, document that.
If it's one of the special keywords, display that documentation.
Otherwise, display an error.

Currently:
user@server:/mnt/c/course$ pydoc -w helloFunc.py
no Python documentation found for 'helloFunc.py'

user@server:/mnt/c/course$ pydoc -w ./helloFunc.py
wrote helloFunc.html

TODO: Update the help strings.


2. Fix command line run error message
Currently, passing an argument (that is not a keyword and is not a filename 
that exists) displays an error message that isn't relevant to this context:

C:\course> py -3 "C:\Program Files (x86)\Python35-32\Lib\pydoc.py"  
notthere.py
No Python documentation found for 'notthere.py'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

This changed from Python2:
C:\course> py -2 "C:\Python27\Lib\pydoc.py"  notthere.py
No Python documentation found for 'notthere.py'.

TODO: Remove the last two lines of the help output from Py3 pydoc when run from 
the command line.


3. Add "-h" command-line argument.
TODO: Add "-h This help summary" to the output of pydoc -h
All the existing options are single letter, so make it just -h
Continue the current behaviour of "no command arguments or switches" displays 
help.


4. TODO: Unknown command line option should give an error.
Currently, pydoc with an unknown command line option doesn't give an error, but 
just displays the standard help:
C:\course> py -3 "C:\Program Files (x86)\Python35-32\Lib\pydoc.py" -j
pydoc - the Python documentation tool

pydoc  ...
Show text documentation on something.   may be the name of a
Python keyword, topic, function, module, or package, or a dotte
...

This can add confusion. It would be more useful to display a specific error, 
and refer users to more help, like ls does:
user@server:~$ ls -j
ls: invalid option -- 'j'
Try 'ls --help' for more information.


5. TODO: Improve HTML output
Oh yes. 
There's a few good contributions on this, but I think Frédéric Jolliton's 
summary is the most succinct.


6. Additional command line argument
To allow certain command line arguments.
Sidenote: Both pod (http://perldoc.perl.org/pod2html.html) and javadoc 
(http://download.java.net/jdk7u2/docs/technotes/tools/solaris/javadoc.html) 
have many command line arguments. I'm not proposing for significant changes, 
but I think the below options would add significantly to the usability, and are 
modeled on pod and javadoc.
It is not intended that pydoc would compete with Sphinx.
TODO:
+ --helpSame as -h for help
+ --css=Override the built-in stylesheet
+ --output or -d or --dir   Output directory name
+ --verbose  More verbose output

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray added the comment:

I've removed the easy tag.  (Aside for those who can do the operation: to 
remove all tags from an issue one must select '-no selection-'; just 
ctrl-clicking the last tag to remove its highlight doesn't work...or at least 
that's what I remember, I didn't actually test it this time.)

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

Changes by R. David Murray :


--
keywords:  -easy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Mariatta Wijaya]

Mariatta Wijaya added the comment:

Hi Andre,

You can subscribe to the core mentorship mailing list here: 

https://mail.python.org/mailman/listinfo/core-mentorship

Once you subscribed, you'll get access to the said discussion :)

It is not required, but it's a great place to ask questions or get help from 
existing core developers.

HTH

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Andre Roberge]

Andre Roberge added the comment:

When rhettinger created this issue, the goal was 

"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. ... Please convert it to simple, validated HTML with the formatting 
moved to a simple, validated default style sheet."

Apparently, the statement of this issue is no longer correct. However, in order 
to do so, one apparently needs to have access to a private list mentioned in a 
comment 
(https://mail.python.org/mailman/private/core-mentorship/2016-August/003622.html)
 

One thing that motivated to submit my tentative "solution" to this issue here 
almost two years ago (solution which, I thought, met the stated goal) was a 
discussion at Pycon as to how one could encourage new contributors.  Is this 
the purpose of the core-mentorship list?  Does one need to join the list if one 
wishes to contribute?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Mariatta Wijaya]

Mariatta Wijaya added the comment:

Thanks for the update, Berker.
Would you be able to remove the 'easy' keyword from this ticket?

I'll keep myself in the nosy list as I'm interested to learn about this anyway 
:)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Berker Peksag]

Berker Peksag added the comment:

(As a result of the discussion at 
http://psf.upfronthosting.co.za/roundup/meta/issue605, I started to re-triage 
all easy issues.)

I don't think this is a suitable task for new contributors. It requires a) good 
HTML and CSS knowledge b) familiarity with pydoc API c) possibly design of a 
new API to finish this task.

There are also some key points that needs to be discussed:

* The current API ties to the dated HTML output and we may not need some of the 
members in the new format (look at the signature of HTMLDoc.section() for 
example) Also, I know HTMLDoc is not a public API, but I saw a number of 
HTMLDoc subclasses in GitHub (even I did it myself in my own projects) so there 
is a risk of breaking working applications. My suggestion is to keep the old 
API as-is and create a new one with new output.

* The another question is that do we need HTMLDoc in 2016? Sphinx, 
sphinx-autodoc and readthedocs.org doing an amazing job and it might be better 
to refer people to alternative solutions (like we did for requests) See also 
https://mail.python.org/mailman/private/core-mentorship/2016-August/003622.html 
for a discussion about this subject.

--
versions: +Python 3.7 -Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
nosy: +Mariatta

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Peter Lovett]

Changes by Peter Lovett :


--
nosy: +PeterLovett

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Adam]

Changes by Adam :


--
nosy: +azsorkin

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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 nbsp;. 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 rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Alex Walters]

Alex Walters added the comment:

Isn't this whats sphinx's apidoc is for?

--
nosy: +tritium

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Changes by Raymond Hettinger raymond.hettin...@gmail.com:


--
keywords: +easy -patch
versions: +Python 3.6 -Python 3.5

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ismail Donmez]

Ismail Donmez added the comment:

Any update on this? Would be nice to have this for 3.5 release.

--
nosy: +cartman

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Andre Roberge]

Andre Roberge added the comment:

If anyone is still interested in this, I did that today (scratching a personal 
itch - not knowing this had been filed before).  

What I have done:
1. Moved all the font/color information to a separate css file
2. Used html5 syntax.
3. Recreated a css style sheet that approximate the current look
4. Created a new, very simple style sheet, that is used as a default. It could 
stand to be greatly improved upon.
5. Checked the validity (W3C) of a sample of the pages generated. This required 
me to include some empty dt and dd tags.
6. Added an option to start the server with an optional, user-defined css 
stylesheet.
7. Made some small unrelated edit (adding spaces after commas, removing
extra spaces before commas, etc.) to reduce the amount of noise from my linter.

I implemented this as a separate project; I did not attempt to run any existing 
unit tests, nor create new ones.  Other than for the additional option (user 
defined style sheet), I tried to avoid making any change to the functionality. 
The styling possible to do is thus limited as I mostly replaced existing 
strings/templates by new ones.

My implementation can be found at https://github.com/aroberge/mod_pydoc
(sorry, not an hg repo).  I did not include a license; I took the existing 
pydoc without asking permission. It can be understood to be under the original 
license.

--
nosy: +aroberge

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Andre Roberge]

Andre Roberge added the comment:

Rather than creating a new branch, I took another copy of pydoc.py, kept its 
name, and only applied the html-related changes in it. (no new  -c option, no 
unrelated PEP8 changes to the best of my knowledge.)  The original pydoc.py 
referred to pydoc_data/_pydoc.css (which was an empty file).  I put the 
minimal new styling option in that file.

I noticed that some former a name=... had no href attribute; I changed the 
name attribute to id, since name is deprecated in html 5.  However, my 
styling option shows these as actual links whereas they are inactive.  An 
example of this can be seen in _codecs

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Andre Roberge]

Andre Roberge added the comment:

I could certainly create a new branch and revert the PEP8 changes and the new 
-c option, but before I do this, could you confirm that the new html output 
would be deemed to be acceptable?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Berker Peksag]

Berker Peksag added the comment:

Thanks! Apparently, we were working on the same issue simultaneously. I was
working on the HTML and CSS parts (didn't touch to Lib/pydoc.py yet). I can
combine our work, if you could

- create a separate branch (no need to be a Hg repo, I can create a
  patch from GitHub)
- revert whitespace and PEP 8 changes
- revert the new -c option in mod_pydoc.py

--
keywords:  -gsoc
nosy: +berker.peksag
versions: +Python 3.5 -Python 3.4

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti added the comment:

 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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ron Adam]

Ron Adam added the comment:

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?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Víctor Terrón]

Víctor Terrón quinta...@gmail.com added the comment:

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.

--
nosy: +vterron

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti ezio.melo...@gmail.com added the comment:

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).

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Changes by Éric Araujo mer...@netwok.org:


--
title: Modernize pydoc to use CSS - Modernize pydoc to use better HTML and 
separate CSS

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Changes by Éric Araujo mer...@netwok.org:


--
assignee: lukasz.langa - eric.araujo
stage:  - patch review
versions: +Python 3.4 -Python 3.3

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10716
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com