We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

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:

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.