An Alternative Python Reference: Using PythonDoc-style Markup for the Library Reference
December 2005 | Fredrik Lundh
I’ve been playing with a new light-weight source format for the official Python library reference, based on a mix of HTML and PythonDoc-style markup. The main goal is to get rid of the current heavy-weight toolchain, and open up for web-based maintenance of the reference material, without losing the current level of semantic information.
Two new tools are developed for this purpose; a translator that uses the HTML generated by the current toolchain as input, and a basic renderer that converts embedded PythonDoc to HTML.
The current (unstyled) rendering can be found here:
(dead link)http://effbot.org/lib
More information can be found here:
Alternative Python Reference
Project Goals
Some goals (for this project):
- Optimize for the Python library reference.
- Easy to write and tweak, with no need for custom editing tools. A plain text editor or a <textarea> should be enough. Online editing with rapid feedback should be trivial to implement.
- Build on existing non-Python-specific documentation standards and tools, where possible (for this project, this means basic html, javadoc, xhtml modules, etc).
- Use a close mapping between markup and semantic model.
- Use a simple but detailed semantic model (see below), based on a Python-specific vocabulary.
- Make it trivial to do basic rendering to HTML (a few re.sub calls should suffice), to enable simple tools (CGI scripts, etc) to be able to render reference documentation.
- Make is easy to do advanced rendering to HTML or XHTML (e.g. typographic issues, navigation, dynamic styling, etc.) and XML models (docbook?). No more -- dashes and silly ``quotes'' in the output.
- Make is possible to do advanced hardcopy rendering (production-quality typesetting).
- Develop conversion tools that does most of the work.
- Support tighter (and 2-way) integration between the library reference and help tools (pydoc, help, inspect, etc) and documentation generators (epydoc, pythondoc, etc).
Some non-goals:
- Perfect conversion tools (some manual cleanup will be necessary).
- Support for all semantic elements used in the current documentation.
- Develop new tools for presentation markup.
- Develop tools suitable for arbitrary documentation tasks. The scope is the library reference manual. Support for tutorials/how-to documents is nice to have, but not a requirement for the first iteration.
- Develop tools for high-quality typesetting.
The semantic model should be simple, python-oriented, and more detailed than today. For example, while a ReST-based solution knows that open in a given context should be rendered in bold, and a LaTeX-based solution knows that the given open is a function, the PythonDoc model also knows that it refers to the os.open function, rather than the built-in open function.
rendered by a django application. hosted by webfaction.