.. This document is *not* meant to be a model for good reStructuredText usage. It is full of external hyperlinks, and makes extensive use of anonymous hyperlink syntax, which is not easy to follow from the source text. Please refer to the processed HTML instead: http://docutils.sourceforge.net/index.html =================================== Docutils: Documentation Utilities =================================== --------------------------------------------------------- Written in Python, for General- and Special-Purpose Use --------------------------------------------------------- :Date: $Date$ The purpose of the Docutils project is to create a set of tools for processing plaintext documentation into useful formats, such as HTML, XML, and LaTeX. Includes reStructuredText_, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language. Several sources are or will be supported: - Standalone files (implemented). - Inline documentation from Python modules and packages, extracted with namespace context. - `PEPs (Python Enhancement Proposals)`_ (implemented). - And others as discovered. Please consider donating to Docutils: |donate| .. |donate| image:: http://images.sourceforge.net/images/project-support.jpg :target: http://sourceforge.net/donate/index.php?group_id=38414 :width: 88 :height: 32 :alt: Support the Docutils project! .. contents:: Getting Started =============== To get up & running quickly, see the Quick-Start_ section of the README_ file. .. _Quick-Start: README.html#quick-start Documentation ============= Please see the `Docutils Project Documentation Overview `_. Feedback ======== To the developers of an open source project, feedback is a great motivator and very welcome. We're working on Docutils in our own way, pushing it along a more-or-less linear path that makes sense to us, but may not necessarily be useful to everyone else. Community feedback helps steer development in immediately useful directions. In other words: if you tell us what you need, you may just get it! If you really need something, please consider contributing_ to Docutils in some way. Please post any feedback to the appropriate `mailing list`_. .. _contributing: `Please Contribute!`_ Project Status ============== The Docutils project began with the merging of the reStructuredText__ parser and the `Python Docstring Processing System`__ projects. The merge has been completed, and those projects are now inactive. __ http://structuredtext.sourceforge.net/ __ http://docstring.sourceforge.net/ Docutils currently consists of a reStructuredText_ parser, readers for standalone files and PEPs_, and writers for HTML, LaTeX, Docutils-native XML, plus pseudo-XML for testing purposes. Writers for DocBook XML and PDF have been started, and a Python source reader (docstring extraction with context) is also under way. There is a lot of design and implementation work to do, which could greatly benefit from a joint effort with existing projects. The project `To Do list`_ is brimming over with ideas. Docutils is in active development and should be considered highly experimental. We're learning as we go. APIs are subject to change at any time. Requirements ============ - Python 2.2 or later [#py21]_ must already be installed to run the code and the test suite. The latest release is recommended. Python is available from http://www.python.org/. - Docutils uses Greg Ward's Optik_/optparse option processing package. It is included in the Docutils distribution. - The `Python Imaging Library`, or PIL, is used for some image manipulation operations if it is installed. .. [#py21] Python 2.1 may be used providing the compiler package is installed. The compiler package can be found in the Tools/ directory of Python's source distribution. .. _Optik: http://optik.sourceforge.net/ .. _Python Imaging Library: http://www.pythonware.com/products/pil/ Download ======== Development Snapshots --------------------- Development snapshots of the project files are available as .tgz tarballs. They are generated automatically from the Subversion repository, usually within an hour of a change being checked in. The snapshots are highly recommended over the "official" releases, as they contain the latest features and bug fixes. However, they may contain transient bugs or incompatibilities. - `Snapshot of Docutils code, tests, documentation, and specifications`__ - `Snapshot of the Sandbox`__ (experimental, contributed code; see `The Sandbox`_ below for details) - `Snapshot of DocFactory project files`__ (this is a subset of the Sandbox snapshot above; you don't need both) - `Snapshot of web files`__ (the files that generate this web site) __ http://docutils.sourceforge.net/docutils-snapshot.tgz __ http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz __ http://docutils.sourceforge.net/docfactory-snapshot.tgz __ http://docutils.sourceforge.net/docutils-web-snapshot.tgz `Anonymous Subversion access`_ is available. You can also `browse the Subversion repository`_ and read the latest README_, HISTORY_, COPYING_, FAQ_ and BUGS_ files. Project Releases ---------------- The `latest project release package`_ (Docutils 0.3.7, 2004-12-24) and past project releases can be downloaded from the `project files page`_. Major changes since Docutils 0.3.5: * A special "`line block`_" syntax useful for addresses, verse, and other cases of significant line breaks has been added (also refer to the `reStructuredText Markup Specification`__). .. _line block: docs/user/rst/quickref.html#line-blocks __ docs/ref/rst/restructuredtext.html#line-blocks * Empty sections are now allowed. * A "raw_" role has been added. .. _raw: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw * The LaTeX writer now escapes consecutive dashes (like "--" or "---") so that they are no longer transformed by LaTeX to en or em dashes. If you want to write en or em dashes using pure ASCII, please refer to the `FAQ entry about non-ASCII characters`__. __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document * A `dependency recorder`_ has been added. .. _dependency recorder: docs/user/config.html#record-dependencies * A directive has been added for `compound paragraphs`_. .. _compound paragraphs: docs/ref/rst/directives.html#compound-paragraph * Many other improvements and bug fixes; see the `history file of Docutils 0.3.7`__. __ 0.3.7/HISTORY.html .. _mailing list: Mailing Lists ============= Users who have questions or need assistance with Docutils or reStructuredText should first check the `Docutils FAQ`_. If the question or problem is not answered there, please `post a message`__ to the `Docutils-users mailing list`__ [#docutils-users]_. Developers can keep up to date and help out by joining the mailing lists. High-level discussions take place on the `Python Documentation Special Interest Group (Doc-SIG) mailing list`__ (email to Doc-SIG@python.org). Two lists have been set up specifically for developers of the Docutils project: - Docutils-develop__, for implementation discussions (email to docutils-develop@lists.sourceforge.net). - Docutils-checkins__, to monitor change/checkin messages (automatically generated; normally read-only). The Doc-SIG_ has greater exposure and is therefore a better forum for general discussions (such as reStructuredText syntax or the high-level Docutils project model), whereas the Docutils-specific lists are more focused on the implementation. You can also access archives of the mailing lists via Gmane: Docutils-users__, Docutils-develop__, Docutils-checkins__ and Doc-SIG__. .. [#docutils-users] Due to overwhelming amounts of spam, the docutils-users@lists.sourceforge.net mailing list has been set up for subscriber posting only. Non-subscribers who post to docutils-users will receive a message with "Subject: Your message to Docutils-users awaits moderator approval". Legitimate messages are accepted and posted as soon as possible (a list administrator must verify the message manually). If you'd like to subscribe to docutils-users, please visit . .. _FAQ: .. _Docutils FAQ: FAQ.html __ mailto:docutils-users@lists.sourceforge.net __ http://lists.sourceforge.net/lists/listinfo/docutils-users __ http://mail.python.org/mailman/listinfo/doc-sig __ http://lists.sourceforge.net/lists/listinfo/docutils-develop __ http://lists.sourceforge.net/lists/listinfo/docutils-checkins __ http://news.gmane.org/gmane.text.docutils.user __ http://news.gmane.org/gmane.text.docutils.devel __ http://news.gmane.org/gmane.text.docutils.cvs __ http://news.gmane.org/gmane.comp.python.documentation The Sandbox =========== The Sandbox__ is a place to play around, to try out and share ideas. It's a part of the Subversion repository but it isn't distributed as part of Docutils releases (you can get a recent tarball from the `development snapshots`_). Each developer who wants to play in it should create their own subdirectory (suggested name: SourceForge ID, or given name + family initial). Please feel free to `visit the sandbox`__. It's OK to make a mess in the Sandbox! But please, play nice. __ __ sandbox/ Sandbox Projects ---------------- Anyone is welcome to contribute to any of these projects. Interested developers are welcome to take on any projects which appear to be dormant. Please direct any email to docutils-develop@lists.sourceforge.net. * ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope" application that is complete and ready to install. * PySource_, by Tony Ibbs, is an experimental Python source Reader. In some form, it will soon become part of core Docutils. There is some related code in David Goodger's sandbox (pysource_reader_) and a `Python Source Reader `__ document. * Docutils interface to PythonPoint_, also by Richard Jones, produces PDF presentations using ReportLabs. * Engelbert Gruber has begun `LaTeX Writer`_ and `ManPage Writer`_ components. * ? has taken over `ReportLabs/PDF Writer`_ components. * Oliver Rutherfurd has begun a `DocBook Writer`_ component and `HT2HTML integration`_ component. * Gunnar Schwant's DocFactory_ is a wxPython GUI application for Docutils. * Aahz has begun an `OpenOffice.org Writer`_. * Ian Bicking is working on code for a Wiki_. * Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely on CSS (stylesheets). * Beni Cherniavsky has written a generic `preprocessing module`_ for roles and/or directives and built preprocessors for TeX math for both LaTeX and HTML output on top of it. * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping to handle everything one might do with docutils. .. _ZReST: sandbox/richard/ZReST/ .. _PySource: sandbox/tibs/pysource/ .. _pysource_reader: sandbox/davidg/pysource_reader/ .. _PythonPoint: sandbox/richard/pythonpoint/ .. _LaTeX Writer: sandbox/grubert/latex/ .. _Manpage Writer: sandbox/grubert/man/ .. _ReportLabs/PDF Writer: sandbox/dreamcatcher/rlpdf/ .. _DocBook Writer: sandbox/oliverr/docbook/ .. _HT2HTML integration: sandbox/oliverr/ht/ .. _DocFactory: sandbox/gschwant/docfactory/doc/ .. _OpenOffice.org Writer: sandbox/aahz/OO/ .. _Wiki: sandbox/ianb/wiki/ .. _simple HTML writer: sandbox/bbum/DocArticle/ .. _preprocessing module: sandbox/cben/rolehack/ .. _Makefile: sandbox/cben/make/ Please Contribute! ================== Please help this project succeed by contributing. We're looking for all kinds of contributions: testing, ideas, code, bug reports, administration, tasty snacks, computer equipment, and large sums of money. There's a `To Do list`_ full of interesting ideas awaiting a champion. If you're interested in participating in any way, please `contact the project coordinator`__. Please consider donating to Docutils: |donate| __ mailto_ Project Links ============= - `Project Summary page`__: `released files`__, `bug reports`__, patches__, `mailing lists`__, and news__. - `Docutils Subversion repository`__ - Project coordinator and architect: `David Goodger`_ - Please direct discussions to the `Python Documentation Special Interest Group (Doc-SIG)`__: doc-sig@python.org. - Powered by |Python|__ - Hosted by |SourceForge|__ __ http://sourceforge.net/projects/docutils/ __ `project files page`_ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 __ http://sourceforge.net/tracker/?group_id=38414&atid=422032 __ http://sourceforge.net/mail/?group_id=38414 __ http://sourceforge.net/news/?group_id=38414 __ Subversion_ __ Doc-SIG_ __ http://www.python.org/ .. |Python| image:: PyBanner016.png .. :border: 0 __ http://sourceforge.net/ .. |SourceForge| image:: http://sourceforge.net/sflogo.php?group_id=38414 :alt: SourceForge Logo .. :border: 0 .. _reStructuredText: rst.html .. _project files page: http://sourceforge.net/project/showfiles.php?group_id=38414 .. _Anonymous Subversion access: http://docutils.sourceforge.net/docs/dev/repository.html .. _Subversion: .. _browse the Subversion repository: http://svn.berlios.de/viewcvs/docutils/ .. _To Do list: docs/dev/todo.html .. _README: README.html .. _HISTORY: HISTORY.html .. _COPYING: COPYING.html .. _BUGS: BUGS.html .. _mailto: .. _David Goodger: mailto:goodger@users.sourceforge.net .. _Doc-SIG: http://www.python.org/sigs/doc-sig/ .. _PEPs: .. _PEPs (Python Enhancement Proposals): http://www.python.org/peps/ .. _latest project release package: http://prdownloads.sourceforge.net/docutils/docutils-0.3.7.tar.gz?download .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: