Éric Araujo <mer...@netwok.org> added the comment: First, thanks for your work on this. I have some feature requests for pydoc too and I’m hoping to work with you in the future :)
I found it more efficient (and fair) to make a new diff instead of listing all nitpicks and have you do the changes. issue_2001_g.diff applies cleanly in py3k. I fixed style issues, removed some docstrings in private classes that were in my eyes unhelpful (the purpose of the class being clear from its name of from a bit of knowledge about http.server), and added the possibility to quit the server with EOF or Ctrl-C. There were a number of trailing spaces in your files. Suggestions: better editor settings, use of hg diff with the color extension, make patchcheck (using Python’s makefile). I have removed the overly long entry from NEWS, I suggest it is used as commit message instead. Here it is, corrected: “Improve Pydoc interactive browsing (#2001). Patch by Ron Adam. * A ``-b`` option to start an enhanced browsing session. * Allow ``-b`` and ``-p`` options to be used together. * Specifying port 0 will pick an arbitrary unused socket port. * A new ``browse()`` function to start the new server and browser. * Show Python version information in the header. * A *Get* field which takes the same input as the ``help()`` function. * A *Search* field which replaces the Tkinter search box. * Lnks to *Module Index*, *Topics*, and *Keywords*. * Improved source file viewing. * An ``HTMLDoc.filelink()`` method. * The ``-g`` option and the ``gui()`` and ``serve()`` functions are deprecated.” issue_2001_f+1.diff shows only the changes I made on top of yours (+ some changes from the py3k branch). Please ask any question you may have about them. Now, those style issues were only the easy parts. Remaining issues (I mean they’re issues to me, you or Nick may disagree): 1) _start_server has a bit of documentation in its docstring, but it’s a private function. Also, two lines are commented so that “make doctest” does not run them, but that is non-obvious and breaks the flow of the text. I recommend doing a combination of those things, at your call: Move those docs to a public function docstring and/or reST doc; move those docs to a comment; don’t use the doctest as test but add a unit test; remove most of the docstring. 2) Functions in methods in classes in functions don’t look great to me. I understand pydoc tries not to import things before it knows it needs them, and it’s also a way of keeping things private, but I think flat is better (more readable) than nested. 3) bltinlink is defined six times. Global (private) function please? :) 4) The HTML has two html elements, two doctypes, an invalid clear attribute on a div element. 5) Last but not least, the deprecations. A few developers had a chat with Raymond Hettinger on IRC yesterday about the cost of deprecations and removals. His defended that their harm (forcing people to change their code) was bigger than their usefulness (catering to esthetic tastes of core developers). How about we arrange the docs and docstrings in order to make the new ways prominent and deprecate the old ones, without any actual code deprecation? ---------- Added file: http://bugs.python.org/file19846/issue_2001_f+1.diff _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue2001> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
