Skip Montanaro <s...@pobox.com> added the comment: >> Did my suggestion to alter pydoc output so it always contains a link >> to the enclosing module's documentation not seem like a reasonable >> compromise?
Catherine> I actually don't understand how that would help. The ``pydoc Catherine> time`` output doesn't include any information about the Catherine> formatting codes (at least, on my system). No, but it does include a link to the full documentation for the time module, so should you need more than is in the docstring, in theory everything you might want would only be one or two clicks away. Catherine> Also, ``pydoc`` isn't available on Windows systems, is it? Catherine> It isn't on mine; is that a quirk of my setup? You can fire up a documentation server using python -m pydoc -g which starts an HTTP server available to dispense documentation for everything in your PYTHONPATH. You can search for "strftime" there, and after a fairly long pause it will present you with a link you can click to get the time module docs. (I think there is a bug in the way it handles errors during import of the various modules.) Alternatively, click the "open browser" button and you will be directed to the front page of the content it serves. The resulting user interface is fairly crude, but if you search for "time" (it's in the lib-dynload section) and click the link provided, it pops up the pydoc documentation for the time module. From there you can click the Module Docs link in the upper right-hand corner to be taken to the full documentation for the time module. Catherine> Yes, certainly, in one place - but isn't it logical for the Catherine> docstring to be that one place? I think most people would argue, "no". Docstrings are helpers. The library reference manual is supposed to be comprehensive. Catherine> Here's where I would suggest drawing the line: if the method Catherine> is unusable without the information, and it's not easy to Catherine> guess or remember, and it's relatively concise, it should be Catherine> in the docstring. This would be a pretty radical change to the documentation. You're asking that either * Docstrings become the comprehensive source of information instead of the library reference manual, or * A fair amount of information be duplicated between the library reference manual and the docstrings. I suggest this discussion be moved to the doc-...@python.org mailing list. Those are the people who would be best equipped to discuss the overall topic. I'm just a single user with my personal perspective on the topic. I'm not the guy who makes these decisions. Skip ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue9650> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com