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