sandbox/package-doc/soc-application.txt

   1 ===========================================
   2  Documenting Python Packages with Docutils
   3 ===========================================
   4
   5 :Author: Lea Wiemann <LeWiemann@gmail.com>
   6 :Date: $Date$
   7 :Revision: $Revision$
   8 :Copyright: This document has been placed in the public domain.
   9
  10 .. note:: This is the Summer of Code '07 application as I originally
  11    submitted it to Google, modulo some minor editing.  For the current
  12    (up-to-date) time line, see `<soc-timeline.html>`_.
  13
  14 Currently, the standard way to document Python Packages is using
  15 Python-specific LaTeX markup.  Many people either do not know LaTeX or
  16 do not want to use it for documentation.  As a result, many Python
  17 packages are not documented using LaTeX.
  18
  19 It would be desirable to have an easy-to-use format to document
  20 packages that is more universally accepted than LaTeX.
  21 ``reStructuredText`` seems like the ideal format for documentation,
  22 and it is already widely known and accepted in the Python community.
  23
  24 I propose to make Docutils ready for documenting Python packages.
  25 This requires implementing the following features:
  26
  27 1. Support for multiple input documents.
  28 2. Add framework support for multiple output documents.
  29 3. Add markup (reStructuredText roles and perhaps directives) that
  30    allows documents to be marked up in a similar fashion as the
  31    current Python-specific LaTeX markup.
  32 4. Add Python-specific LaTeX output.
  33 5. Add HTML support for multiple output documents; add styling for the
  34    HTML output that resembles the look of current Python module
  35    documentation generated by the current system as closely as
  36    possible.
  37
  38
  39 Time Line
  40 =========
  41
  42 present - May 27
  43     Have some preliminary discussion on the Docutils mailing list
  44     about how each step should be implemented.  I expect that much
  45     design discussion will still take place during the implementation
  46     phase as issues arise.
  47
  48 May 28 - June 10
  49     Add support for multiple input documents.  This may involve adding
  50     a new format for a top-level "master" document which references
  51     all files in the documentation.
  52
  53 June 11 - June 17
  54     Design and implement framework support for multiple output
  55     documents.
  56
  57 June 18 - June 24
  58     Implement Python-specific LaTeX output.
  59
  60 June 25 - July 1
  61     Add reStructuredText markup such as roles and possibly directives
  62     similar to the current Python-specific LaTeX markup.
  63
  64 July 2 - July 13
  65     Implement support for multiple output documents in the HTML
  66     writer.  Add styling for the resulting HTML to make it resemble
  67     the current output of the LaTeX to HTML tool chain.
  68
  69 August 5 - August 12
  70      Create user documentation.  This is crucial for the success and
  71      adoption of reStructuredText-based package documentation.
  72
  73 August 13 - August 20
  74      Buffer time.
  75
  76
  77 Personal Background
  78 ===================
  79
  80 I have been working on the Docutils project since April 2004, so I
  81 know its internals very well.  I definitely plan to continue working
  82 on it after this summer.  I have given talks and attended sprints
  83 about Docutils at PyCon '06, EuroPython '06, and PyCon '07.
  84
  85 David Goodger, the Docutils maintainer, is willing to be my mentor for
  86 this project.  Thanks David!
  87
  88
  89 Conclusion
  90 ==========
  91
  92 I would be excited to receive funding for this project over the
  93 summer!  I will be happy to answer any questions; you can reach me via
  94 email at LeWiemann@gmail.com.