Documenting Python Packages with Docutils

Author:

Lea Wiemann <LeWiemann@gmail.com>

Date:
2007-05-31
Revision:
5172
Copyright:
This document has been placed in the public domain.

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.