Mailman 3 May 2007 - Doc-SIG

[Pointer] Multi-file input
by Lea Wiemann May 31, 2007

May 31, 2007

Hi everyone, I'm starting phase 1 of my Google Summer of Code project (Documenting Python Packages with Docutils), which is multi-file input for Docutils/reStructuredText (NB multi-file input, not output). I'm moving all the discussion to Docutils-develop (http://docutils.sf.net/docs/user/mailing-lists.html#docutils-develop), because I don't want to flood Doc-SIG with technical details. Feel free to join in! Best wishes, Lea

1 0

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by Ron Adam May 26, 2007

May 26, 2007

Georg Brandl wrote: > Hi, > > We managed to get an up to date version of the web version of the docs running > on the server. The address is still the same (http://pydoc.gbrandl.de:3000) and > it's also still running on top of wsgiref. > > Changes so far: > * comments: each page that is generated from an rst file can have some > comments attached to it. Commenting doesn't require registration at the > moment. > * antispam with optional reverse captcha (captcha for bots, a hidden input > field named "homepage" which bots hopefully fill out, dumb as they are) and > a regular expression filter rules based on MoinMoin's BadContent file. > * administration panel for moderating comments. You can find the admin panel > at http://pydoc.gbrandl.de:3000/admin/ -- login credentials are > testuser:password) > * feeds for comments on a page or the last n comments on the whole site. > * source view is text only (again). > > What still works: > * intelligent error pages: if a page does not exist the URL path is used to > conduct a fuzzy keyword search (see below). > * fuzzy keyword search: "os.path.exists" jumps to the entry, "os.paht.exists" > shows some possibilities. > > What needs to be implemented: > * full text search > * proposing documentation patches > > Note that the comment area is really, really dark, that's intentional. This is > meant to visually separate comments from the official docs, but if the constrast > is deemed to unsettling, another way can be found. > > Also, we're experimenting with alternate stylesheets, e.g. placing the sidebar > on the right of the main text, or a "traditional" style for those liking the > original docs' style. > > In any case, we're waiting for your input! > > cheers, > Georg and Armin Yes, the comments are a bit too dark. The separation could be done better by moving it below the footer. Or better yet, duplicate the navigation bar between the the document page and the comments. ------------------------------------------------ crumbs navagation ------------------------------------------------ side | main page bar | | | ------------------------------------------------ crumbs navagation ------------------------------------------------ User Comment section ------------------------------------------------ copy right ------------------------------------------------ The user comment section could have it's own side bar if that's desirable. Also the python version information needs to be on every page someplace. Ron

1 0

The docs, reloaded
by Georg Brandl May 22, 2007

May 22, 2007

Hi, over the last few weeks I've hacked on a new approach to Python's documentation. As Python already has an excellent documentation framework, the docutils, with a readable yet extendable markup format, reST, I thought that it should be possible to use those instead of the current LaTeX->latex2html toolchain. For the impatient: the result can be seen at <http://pydoc.gbrandl.de>. I've written a converter tool that handles most of the LaTeX markup and turns it into reST, as well as a builder tool that adds many custom directives and roles, and also features like index generation and cross-document linking. (What you can see at the URL is a completely statical version of the docs, as it would be shipped with the distribution. For the real online docs, I have more plans; I'll come to that later.) So why the effort? Here's a partial list of things that have already been improved: - the source is much more readable (for examples, try the "view source" links in the left navbar) - all function/class/module names are properly cross-referenced - the HTML pages are generated from templates, using a language similar to Django's template language - Python and C code snippets are syntax highlighted - for the offline version, there's a JavaScript enabled search function - the index is generated over all the documentation, making it easier to find stuff you need - the toolchain is pure Python, therefore can easily be shipped What more? If there is support for this approach, I have plans for things that can be added to the online version: - a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would redirect you to the matching location. - "interactive patching": provide an "propose edit" link, leading to a Wiki-like page where you can edit the source. From the result, a diff is generated, which can be accepted, edited or rejected by the development team. This is even more straightforward than plain old comments. - the same infrastructure could be used for developers, with automatic checkin into subversion. - of course, plain old comments can be useful too. Concluding, a small caveat: The conversion/build tools are, of course, not complete yet. There are a number of XXX comments in the text, most of them indicate that the converter could not handle a situation -- that would have to be corrected once after conversion is done. Waiting for comments! Cheers, Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.

12 15

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by skip＠pobox.com May 22, 2007

May 22, 2007

>>> What would be my choices for add math to the documentation? >> Where in the current documentation is there any math notation /at >> all/? Georg> There is exactly one instance of LaTeX math in the whole docs, Georg> it's in the description of audioop, AFAIR, an contains a sum over Georg> square roots... Georg> So, that's not really a concern of mine ;) You must realize that people will use the core tools to create documentation for third party packages which aren't in the core. If you replace LaTeX with something else I think you need to keep math in mind whether it's used in the core documentation or not. Skip

8 10

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by skip＠pobox.com May 21, 2007

May 21, 2007

>> You must realize that people will use the core tools to create >> documentation for third party packages which aren't in the core. If >> you replace LaTeX with something else I think you need to keep math >> in mind whether it's used in the core documentation or not. Martin> I disagree. The documentation infrastructure of Python should Martin> only consider the needs of Python itself. If other people can Martin> use that infrastructure for other purposes, fine - if they find Martin> that it does not meet their needs, they have to look elsewhere. Then I submit that you are probably removing some significant piece of functionality from the provided documentation toolchain which some people probably rely on. After all, that's what LaTeX excels at. They will be able to continue to use the old tools, but where will they get them if they are no longer part of Python? Skip

2 1

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by skip＠pobox.com May 21, 2007

May 21, 2007

Brett> Martin beat me to my comment. =) Python's needs should come Brett> first, period. If Georg wants to add math support, fine. But Brett> honestly I would rather he spend his time on Python-specific Brett> stuff then get bogged down to support possible third parties. I think the people who have responded to my comment read too much into it. Nowhere do I think I asked Georg to write an equation typesetter to include in the Python documentation toolchain. I asked that math capability be considered. I have no idea what tools he used to build his new documentation set. I only briefly glanced at a couple of the output pages. I think what he has done is marvelous. However, I don't think the door should be shut on equation display. Is there a route to it based on the tools Georg is using? If not, then I think some accommodation should be made. I'm being vague here on purpose because I'm unfamiliar with the available tools. The one thing I do know is that LaTeX provides that today and by removing it from the toolchain you have removed a significant piece of functionality. Skip

1 0

Re: [Doc-SIG] The docs, reloaded
by Neal Becker May 21, 2007

May 21, 2007

Georg Brandl wrote: > Scott Dial schrieb: >> Neal Becker wrote: >>> Sounds very interesting. I just have one concern/question. I hope that >>> while moving away from latex, we are not precluding the ability to write >>> math as part of the documentation. What would be my choices for add >>> math >>> to the documentation? Hopefully using latex, since there really isn't >>> AFAIK any other competitor for this. >>> >> >> Where in the current documentation is there any math notation /at all/? >> In all my reading of it, I have not run across anything that appeared >> like it was being used. Besides that question, is the full power of >> LaTeX math notation really necessary here? I somehow doubt anything more >> than simple expressions of runtime performance and container behaviors >> are appropriate for any documentation we have. > > There is exactly one instance of LaTeX math in the whole docs, it's in the > description of audioop, AFAIR, an contains a sum over square roots... > > So, that's not really a concern of mine ;) > > Georg > There is an effort as part of numpy to come up with a new system using docstrings. It seems to me it would be unfortunate if these two efforts were not coordinated.

4 4

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by Martin Blais May 20, 2007

May 20, 2007

On 5/20/07, Georg Brandl <g.brandl(a)gmx.net> wrote: > > Very nice! As well as looking very attractive and professional, the all-Python > > toolset should make it easier to build the documentation - I've not been > > able to get a trouble-free setup of the docs toolchain on Windows. > > Yep. As it is now, you need three packages from the Cheese Shop: > Docutils, Pygments (the highlighter) and Jinja (the templating engine). > This shouldn't be problematic, though they could also be stripped down > and included. This is great. IMHO if this is to compete to become the official Python docs, I would argue for even less dependencies, even at the cost of more generic/bland output, for portability reasons and to stimulate greater adoption. If we can make some of those dependencies optional and only rely on docutils, that could make it ubiquitous. Another thing to keep in mind: I don't know if the directives you defined are very generic, but if they are, it would be interesting to consider migrating them up into docutils (if it makes sense), and see if they could support documenting other programming languages. Could this be a language-independent documenting toolkit? Could we document LISP or Ruby code with it? Georg, thanks again!

1 0

Re: [Doc-SIG] [Python-Dev] The docs, reloaded
by Laura Creighton May 19, 2007

May 19, 2007

Wow. Nice job. Thank you so very much. Laura

1 0

Updating docs.python.org to 2.5.1 docs?
by A.M. Kuchling May 18, 2007

May 18, 2007

Does the content on docs.python.org need to be updated to the Python 2.5.1 docs? The release date on the page is given as September 19, which is the 2.5 release date. --amk

1 0