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 <name> ...
        Show text documentation on something.  <name> 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:
+ --help        Same as -h for help
+ --css=        Override the built-in stylesheet
+ --output or -d or --dir   Output directory name
+ --verbose  More verbose output