Differences between revisions 11 and 53 (spanning 42 versions)
⇤ ← Revision 11 as of 2004-01-19 20:57:25 →
Size: 5214
Editor: cpc1-cmbg1-4-0-cust63
Comment:
← Revision 53 as of 2007-02-23 10:34:59 → ⇥
Size: 10522
Editor: PaulBoddie
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
(For the Docutils sprint at PyCon2007, see ["PyCon2007/DocutilsSprint"].
For the Docutils sprint at PyCon2006, see ["PyCon2006/Sprints/DocutilsSprint"].)
Line 3: Line 6:
For information about the other sprints going on at ["PyConDC2004"],
please see SprintPlan2004.		 PyConDC2004 is over. See [http://starship.python.net/~goodger/pycon_dc_2004/ A Week at PyCon DC 2004] for a narrative account of events.
Line 6: Line 8:
For introductory information, please see the 2003 SprintPlan. For introductory information and information about the other sprints
going on at ["PyConDC2004"], please see SprintPlan2004.

We also had a birds-of-a-feather session; see DocutilsBof.

Also see the [http://docutils.sourceforge.net Docutils home page] and the [http://docutils.sourceforge.net/rst.html reStructuredText home page].
Line 11: Line 18:
The sprints at ["PyConDC2004"] are to be held from March 20 (Saturday)
through March 23 (Tuesday), totalling 4 days. How long should the
Docutils sprint be? It probably depends on the participants, so
please voice your opinions here or [mailto:goodger@python.org email me].		 The sprints at ["PyConDC2004"] were held from March 20 (Saturday)
through March 23 (Tuesday), for a total of 4 days. I was there
for all 4 sprint days, and sprinters joined in as they were able.

Please feel free to comment here or [mailto:goodger@python.org email me].


=== Cost ===

There was no cost to attend the sprints beyond being present.
Line 19: Line 32:
How many participants? Please [mailto:goodger@python.org email me] or
edit this page directly if you'd like to participate.		 Everyone was welcome! No prior Docutils hacking experience was required.
Participants were either experienced Python programmers, or interested
in documentation.
Line 22: Line 36:
 * David Goodger (coach) [mailto:goodger@python.org send me email] Here are the sprinters who attended:

 * [mailto:goodger@python.org David Goodger] (coach)
 * [mailto:oliver@rutherfurd.net Ollie Rutherfurd] (Saturday and Sunday)
 * [mailto:fdrake@acm.org Fred Drake] (Saturday)
 * [mailto:ianb@colorstudy.com Ian Bicking] (Saturday, Monday, & Tuesday)
 * [mailto:aahz@pythoncraft.com Aahz] (All four days)
 * [mailto:edloper@gradient.cis.upenn.edu Edward Loper] (Sunday through Tuesday)
 * [mailto:tracer@axiomfire.com Tracy Ruggles] (Sunday & Tuesday?)
 * [mailto:gilbert@voxmea.net Matt Gilbert] (All four days)
 * [mailto:sholden@holdenweb.com Steve Holden] (Saturday and Sunday)
 * Bill Sconce (all four days)
 * Andrew Kuchling (Saturday)
 * Reggie Dugard (Sunday through Tuesday)
 * Mike Orr (Monday)
 * Lloyd Kvam (Tuesday)
 * Laura Creighton (Sunday through Tuesday)
 * Jacob Hallen (Sunday through Tuesday)
Line 27: Line 58:
This sprint and my participation at ["PyConDC2004"] are being sponsored by
the [http://www.python.org/psf Python Software Foundation (PSF)],
[http://WingIDE.com Archaeopteryx Software], and individual 		This sprint and my participation at ["PyConDC2004"] were sponsored by
Silver Sponsor [http://WingIDE.com Wing IDE (Archaeopteryx Software)], the
[http://www.python.org/psf Python Software Foundation (PSF)], and individual
Line 31: Line 62:

In order to minimize expenses, I'm hoping to find someone willing to
put me up in a spare bed, sofa, or patch of floor, from March 19 to
March 27. If you can help, please
[mailto:goodger@python.org send me email] as soon as possible.
Thanks!
Line 41: Line 66:
What would participants like to accomplish? Choose from among the
ideas below or add new ones. Register your votes below, and feel free
to comment.		 Each sprint day began with an interactive overview of the Docutils architecture and codebase.
Line 45: Line 68:
The sprint should begin with an introduction to Docutils and
reStructuredText: their purpose, future direction, and current
implementation. How long should it be? Should there be a long
preliminary lecture covering a lot of ground, or a minimal overview
(with the possibility of further dicsussions as needed)?		 I will update this page with actual results from the sprint. For now,
here is the original list of ideas for the sprint, in no particular order:
Line 51: Line 71:
Here are ideas for the sprint, in no particular order:

 * Python source reader (autodocumentation subsystem). Ideas:		  * '''PROGRESS!''' Python source reader (autodocumentation subsystem). There's a lot of support for this. Ideas:
Line 55: Line 73:
   * [http://docutils.sf.net/spec/pysource.html detailed exploration of some ideas]
Line 57: Line 76:
   * [http://docutils.sf.net/sandbox/sandbox/davidg/pysource_reader DavidG's sandbox code (incomplete)]
   * [http://docutils.sf.net/sandbox/sandbox/tibs/ Tibs' sandbox code (incomplete)]		    * [http://docutils.sf.net/sandbox/davidg/pysource_reader DavidG's sandbox code (incomplete)]
   * [http://docutils.sf.net/sandbox/tibs/ Tibs' sandbox code (incomplete)]
   * [http://docutils.sourceforge.net/sandbox/ianb/extractor/ IanB's sandbox code (hack)]
   * Extending EpyDoc with python source parsing (this has been on the todo list for a while now).
Line 62: Line 83:
 * Doc``Py (Python's dialect of LaTeX) writer completion -- would allow easier entry for documentation newbies, "make authorship more accessible" ([http://docutils.sf.net/sandbox/dkuhlman/ initial implementation]).  * '''PROGRESS!''' Doc``Py (Python's dialect of LaTeX) writer completion -- would allow easier entry for documentation newbies, "make authorship more accessible" ([http://docutils.sf.net/sandbox/edloper/docpy/ initial implementation]). ''This would be a major interest for me, I would like to make the Python docs more accessible to new authors -- SH''
Line 64: Line 85:
 * HTML fragment writer -- establish API (useful for ht2html and templating systems). ([http://docutils.sf.net/spec/notes.html#html-fragments Notes], and [http://docutils.sf.net/sandbox/oliverr/ht/ related work].)  * '''DONE!''' Add an [http://docutils.sourceforge.net/sandbox/edloper/epytext epytext parser] (requires [http://epydoc.sourceforge.net epydoc]).

 * '''DONE!''' HTML fragment writer -- establish API (useful for ht2html and templating systems). ([http://docutils.sf.net/spec/notes.html#html-fragments Notes], and [http://docutils.sf.net/sandbox/oliverr/ht/ related work].) Fred Drake and Mike Orr are both interested in this.

   Reggie Dugard implemented a new docutils.core.publish_parts() convenience function, with Mike Orr's initial help.

 * [http://www.w3.org/TR/2003/WD-xhtml2-20030506/ XHTML 2.0] writer. Though the spec is in the "working draft" stage, it would be nice to start experimenting with it. -- ''Fred Drake''
Line 67: Line 94:
   * Open``Office.org ([http://docutils.sf.net/sandbox/aahz/OO/ Aahz's sandbox] & [http://docutils.sf.net/sandbox/pobrien/OpenOffice/ Patrick O'Brien's sandbox]; which is based on which?)
   * Doc``Book ([http://docutils.sf.net/sandbox/oliverr/docbook/ Oliver Rutherfurd's sandbox])		    * Open``Office.org (original hack in
   [http://docutils.sf.net/sandbox/aahz/OO/ Aahz's sandbox] & mods in
   [http://docutils.sf.net/sandbox/pobrien/OpenOffice/ Patrick O'Brien's sandbox])

 * '''PROGRESS!''' Doc``Book ([http://docutils.sf.net/sandbox/oliverr/docbook/ Oliver Rutherfurd's sandbox])
Line 70: Line 100:

 * '''PROGRESS!''' Aahz will be running a sprint to create a base protocol for binary
 writers, leading to a reactoring of the Open``Office.org writer and a
 new MIFWriter for Frame.
Line 75: Line 109:
 * Nested inline markup -- may require new inline markup parser with proper tokenization & lexing. Or stack-based. Currently under discussion on the [http://lists.sourceforge.net/lists/listinfo/docutils-develop docutils-develop mailing list].  * Nested inline markup -- may require new inline markup parser with proper tokenization & lexing. Or stack-based. Currently under discussion on the [http://lists.sourceforge.net/lists/listinfo/docutils-develop docutils-develop mailing list].  David Abrahams has checked in an initial implementation to the "nesting" branch under CVS.
Line 79: Line 113:
 * Complete [http://docutils.sf.net/spec/doctree.html "The Docutils Document Tree"] reference doc.  * '''PROGRESS!''' Complete [http://docutils.sf.net/spec/doctree.html "The Docutils Document Tree"] reference doc.
Line 81: Line 115:
 * Wikis ([http://docutils.sf.net/sandbox/ianb/wiki/ Ian Bicking's sandbox], [http://docutils.sourceforge.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax FAQ entry]). If MoinMoin is python.org's official wiki, it would be nice if it fully supported reStructuredText ;-).  * '''PROGRESS!''' Wikis ([http://docutils.sf.net/sandbox/ianb/wiki/ Ian Bicking's sandbox], [http://docutils.sourceforge.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax FAQ entry]). If MoinMoin is python.org's official wiki, it would be nice if it fully supported reStructuredText ;-).
Line 83: Line 117:
 * [http://docutils.sf.net/spec/notes.html#bugs Squash bugs]  * '''PROGRESS!''' [http://docutils.sf.net/spec/notes.html#bugs Squash bugs]
Line 93: Line 127:
 * More ideas in the [http://docutils.sf.net/spec/notes.html#to-do to-do list].  * Extend EpyDoc support for ReStructuredText (e.g., for LaTeX output).

 * Auto-numbering syntax.

   * The ability to reference (internal link) an auto-numbered section sans the number.

 * (One just slightly off-topic idea would be to extend an existing documentation generator, such as EpyDoc, to support Zope-style interfaces. This would be especially nice since EpyDoc already supports reStructuredText. -- ''Fred Drake'')
   * (EpyDoc *should* already support Zope-style interfaces. If not, then please let me know where it needs to be extended for proper support. -- ''Edward Loper'')

 * '''DONE!''' implemented a directive to embed the ABC music notation in reStructuredText.

There are more ideas in the [http://docutils.sf.net/spec/notes.html#to-do Docutils to-do list].
Line 103: Line 148:

I'd be very interested in working on the/a Python source code reader -- it seems like the giant missing piece of docutils. -- ''Ian Bicking''

Two 2-day sprints would be better for me. I wasn't planning to attend any sprint, but Docutils is tempting me. I'd most likely attend Monday-Tuesday. I'm not that good at understanding intricate parser code, but perhaps I can work on some other aspect. My wishlist item is for the HTML generator to just produce an HTML fragment I can plug into a larger page, rather than all the header/footer/style stuff it adds. There has also been much interest in our local Python user group about having a ReST syntax in MoinMoin. -- ''Mike Orr''

An enhanced client API with better support for [http://docutils.sf.net/spec/notes.html#html-fragments writing fragments] would be ''really'' nice to have; I'd be willing to spend some time on that as well. Each time I have tried to make a simple script that used docutils in some way, the API has been difficult to figure out. It may be that documentation is all that's needed, or just a more-visible entry point into existing documentation, but I know how hard that is to do. I think it would be worth having at least a little brain-storming session to figure out where people are getting hung up on the API and letting you tell us how much of it is there in some form already, and guiding an effort to make it more effectively exposed. Whether that's documentation, a little code, or a pile of new stuff, I don't know, but my past explorations make me think there's some limited amount of "API stuff" that needs to be done. It is unlikely I'll be able to sprint on this topic Monday/Tuesday though. -- ''Fred Drake''

I'll probably be there for all four days. Anyone who's interested in automatic API documentation generation might want to take a look at EpyDoc, which currently supports reStructuredText. I'd like to work on extending it with better docutils support, and improve it in other ways. -- ''Edward Loper''

I use EpyDoc quite a bit, and would like to help with it's docutils support. And, just in general, would like to help out the docutils project. -- ''Tracy Ruggles''

I'd love to get the Doc``Book writer finished up -- I think it's pretty close. It needs tests, better bibliographic field handling, and probably a bit of polishing. -- ''Ollie Rutherfurd''

(For the Docutils sprint at PyCon2007, see ["PyCon2007/DocutilsSprint"]. For the Docutils sprint at PyCon2006, see ["PyCon2006/Sprints/DocutilsSprint"].)

Preliminaries

PyConDC2004 is over. See [http://starship.python.net/~goodger/pycon_dc_2004/ A Week at PyCon DC 2004] for a narrative account of events.

For introductory information and information about the other sprints going on at ["PyConDC2004"], please see SprintPlan2004.

We also had a birds-of-a-feather session; see DocutilsBof.

Also see the [http://docutils.sourceforge.net Docutils home page] and the [http://docutils.sourceforge.net/rst.html reStructuredText home page].

Duration

The sprints at ["PyConDC2004"] were held from March 20 (Saturday) through March 23 (Tuesday), for a total of 4 days. I was there for all 4 sprint days, and sprinters joined in as they were able.

Please feel free to comment here or [mailto:goodger@python.org email me].

Cost

There was no cost to attend the sprints beyond being present.

Sprinters

Everyone was welcome! No prior Docutils hacking experience was required. Participants were either experienced Python programmers, or interested in documentation.

Here are the sprinters who attended:

Sponsorship

This sprint and my participation at ["PyConDC2004"] were sponsored by Silver Sponsor [http://WingIDE.com Wing IDE (Archaeopteryx Software)], the [http://www.python.org/psf Python Software Foundation (PSF)], and individual contributors. Thank you all!

Sprint Topic Ideas

Each sprint day began with an interactive overview of the Docutils architecture and codebase.

I will update this page with actual results from the sprint. For now, here is the original list of ideas for the sprint, in no particular order:

There are more ideas in the [http://docutils.sf.net/spec/notes.html#to-do Docutils to-do list].

Comments

Please feel free to add any comments you like. Include your name for feedback; anonymous comments OK too. I hope to see you at PyCon! -- David Goodger

I shan't be able to make PyCon (no surprise there), but I hope the sprint goes really well. I have no objection at all if one of the items of work is the pysource reader, whether based on my work or not - indeed, I'd love to see a working implementation out there. -- Tibs

I'd be very interested in working on the/a Python source code reader -- it seems like the giant missing piece of docutils. -- Ian Bicking

Two 2-day sprints would be better for me. I wasn't planning to attend any sprint, but Docutils is tempting me. I'd most likely attend Monday-Tuesday. I'm not that good at understanding intricate parser code, but perhaps I can work on some other aspect. My wishlist item is for the HTML generator to just produce an HTML fragment I can plug into a larger page, rather than all the header/footer/style stuff it adds. There has also been much interest in our local Python user group about having a ReST syntax in MoinMoin. -- Mike Orr

An enhanced client API with better support for [http://docutils.sf.net/spec/notes.html#html-fragments writing fragments] would be really nice to have; I'd be willing to spend some time on that as well. Each time I have tried to make a simple script that used docutils in some way, the API has been difficult to figure out. It may be that documentation is all that's needed, or just a more-visible entry point into existing documentation, but I know how hard that is to do. I think it would be worth having at least a little brain-storming session to figure out where people are getting hung up on the API and letting you tell us how much of it is there in some form already, and guiding an effort to make it more effectively exposed. Whether that's documentation, a little code, or a pile of new stuff, I don't know, but my past explorations make me think there's some limited amount of "API stuff" that needs to be done. It is unlikely I'll be able to sprint on this topic Monday/Tuesday though. -- Fred Drake

I'll probably be there for all four days. Anyone who's interested in automatic API documentation generation might want to take a look at EpyDoc, which currently supports reStructuredText. I'd like to work on extending it with better docutils support, and improve it in other ways. -- Edward Loper

I use EpyDoc quite a bit, and would like to help with it's docutils support. And, just in general, would like to help out the docutils project. -- Tracy Ruggles

I'd love to get the DocBook writer finished up -- I think it's pretty close. It needs tests, better bibliographic field handling, and probably a bit of polishing. -- Ollie Rutherfurd

DocutilsSprint (last edited 2015-01-10 12:15:15 by WolfgangMaier)

Unable to edit the page? See the FrontPage for instructions.