web/index.txt

   1 .. This document is *not* meant to be a model for good
   2    reStructuredText usage.  It is full of external hyperlinks, and
   3    makes extensive use of anonymous hyperlink syntax, which is not
   4    easy to follow from the source text.  Please refer to the processed
   5    HTML instead: http://docutils.sourceforge.net/index.html
   6
   7 ===================================
   8  Docutils: Documentation Utilities
   9 ===================================
  10 ---------------------------------------------------------
  11  Written in Python, for General- and Special-Purpose Use
  12 ---------------------------------------------------------
  13
  14 :Date: $Date$
  15
  16 The purpose of the Docutils project is to create a set of tools for
  17 processing plaintext documentation into useful formats, such as HTML,
  18 XML, and LaTeX.  Includes reStructuredText_, the easy to read, easy to
  19 use, what-you-see-is-what-you-get plaintext markup language.  Several
  20 sources are or will be supported:
  21
  22 - Standalone files (implemented).
  23 - Inline documentation from Python modules and packages, extracted
  24   with namespace context.
  25 - `PEPs (Python Enhancement Proposals)`_ (implemented).
  26 - And others as discovered.
  27
  28 Please consider donating to Docutils: |donate|
  29
  30 .. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
  31    :target: http://sourceforge.net/donate/index.php?group_id=38414
  32    :width: 88
  33    :height: 32
  34    :alt: Support the Docutils project!
  35
  36 .. contents::
  37
  38
  39 Getting Started
  40 ===============
  41
  42 To get up & running quickly, see the Quick-Start_ section of the
  43 README_ file.
  44
  45 .. _Quick-Start: README.html#quick-start
  46
  47
  48 Documentation
  49 =============
  50
  51 Please see the `Docutils Project Documentation Overview
  52 <docs/index.html>`_.
  53
  54
  55 Feedback
  56 ========
  57
  58 To the developers of an open source project, feedback is a great
  59 motivator and very welcome.  We're working on Docutils in our own way,
  60 pushing it along a more-or-less linear path that makes sense to us,
  61 but may not necessarily be useful to everyone else.  Community
  62 feedback helps steer development in immediately useful directions.
  63
  64 In other words: if you tell us what you need, you may just get it!  If
  65 you really need something, please consider contributing_ to Docutils
  66 in some way.
  67
  68 Please post any feedback to the appropriate `mailing list`_.
  69
  70 .. _contributing: `Please Contribute!`_
  71
  72
  73 Project Status
  74 ==============
  75
  76 The Docutils project began with the merging of the reStructuredText__
  77 parser and the `Python Docstring Processing System`__ projects.  The
  78 merge has been completed, and those projects are now inactive.
  79
  80 __ http://structuredtext.sourceforge.net/
  81 __ http://docstring.sourceforge.net/
  82
  83 Docutils currently consists of a reStructuredText_ parser, readers for
  84 standalone files and PEPs_, and writers for HTML, LaTeX,
  85 Docutils-native XML, plus pseudo-XML for testing purposes.  Writers
  86 for DocBook XML and PDF have been started, and a Python source reader
  87 (docstring extraction with context) is also under way.  There is a lot
  88 of design and implementation work to do, which could greatly benefit
  89 from a joint effort with existing projects.  The project `To Do list`_
  90 is brimming over with ideas.
  91
  92 Docutils is in active development and should be considered highly
  93 experimental.  We're learning as we go.  APIs are subject to change at
  94 any time.
  95
  96
  97 Requirements
  98 ============
  99
 100 - Python 2.2 or later [#py21]_ must already be installed to run the
 101   code and the test suite.  The latest release is recommended.  Python
 102   is available from http://www.python.org/.
 103
 104 - Docutils uses Greg Ward's Optik_/optparse option processing package.
 105   It is included in the Docutils distribution.
 106
 107 - The `Python Imaging Library`, or PIL, is used for some image
 108   manipulation operations if it is installed.
 109
 110 .. [#py21] Python 2.1 may be used providing the compiler package is
 111    installed.  The compiler package can be found in the Tools/
 112    directory of Python's source distribution.
 113
 114 .. _Optik: http://optik.sourceforge.net/
 115 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 116
 117
 118 Download
 119 ========
 120
 121 Development Snapshots
 122 ---------------------
 123
 124 Development snapshots of the project files are available as .tgz
 125 tarballs.  They are generated automatically from CVS, usually within
 126 an hour of a change being checked in.  The snapshots are highly
 127 recommended over the "official" releases, as they contain the latest
 128 features and bug fixes.  However, they may contain transient bugs or
 129 incompatibilities.
 130
 131 - `Snapshot of Docutils code, tests, documentation, and
 132   specifications`__
 133 - `Snapshot of the Sandbox`__ (experimental, contributed code; see
 134   `The Sandbox`_ below for details)
 135 - `Snapshot of DocFactory project files`__ (this is a subset of the
 136   Sandbox snapshot above; you don't need both)
 137 - `Snapshot of web files`__ (the files that generate this web site)
 138
 139 __ http://docutils.sourceforge.net/docutils-snapshot.tgz
 140 __ http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz
 141 __ http://docutils.sourceforge.net/docfactory-snapshot.tgz
 142 __ http://docutils.sourceforge.net/docutils-web-snapshot.tgz
 143
 144 `Anonymous CVS access`_ is available.  You can also `browse the CVS
 145 repository`_ and read the latest README_, HISTORY_, COPYING_, FAQ_ and
 146 BUGS_ files.
 147
 148
 149 Project Releases
 150 ----------------
 151
 152 The `latest project release package`_ (Docutils 0.3.5, 2004-07-29) and
 153 past project releases can be downloaded from the `project files
 154 page`_.  This release fixes many bugs, adds some features, and is
 155 highly recommended over prior versions.
 156
 157 Major changes since Docutils 0.3.3:
 158
 159 * improved, extended and reorganized documentation_
 160 * new csv-table_ directive
 161 * many minor improvements, additions and bug fixes
 162
 163 For a more detailed list of changes, read the `HISTORY of Docutils
 164 0.3.5`__.
 165
 166 Thanks to Felix Wiemann for putting together this release!
 167
 168 .. _documentation: docs/index.html
 169 .. _csv-table: docs/ref/rst/directives.html#csv-table
 170 .. __: 0.3.5/HISTORY.html
 171
 172
 173 .. _mailing list:
 174
 175 Mailing Lists
 176 =============
 177
 178 Users who have questions or need assistance with Docutils or
 179 reStructuredText should first check the `Docutils FAQ`_.  If the
 180 question or problem is not answered there, please `post a message`__
 181 to the `Docutils-users mailing list`__ [#docutils-users]_.
 182
 183 Developers can keep up to date and help out by joining the mailing
 184 lists.
 185
 186 High-level discussions take place on the `Python Documentation Special
 187 Interest Group (Doc-SIG) mailing list`__ (email to
 188 Doc-SIG@python.org).
 189
 190 Two lists have been set up specifically for developers of the Docutils
 191 project:
 192
 193 - Docutils-develop__, for implementation discussions
 194   (email to docutils-develop@lists.sourceforge.net).
 195 - Docutils-checkins__, to monitor CVS checkin messages (automatically
 196   generated; normally read-only).
 197
 198 The Doc-SIG_ has greater exposure and is therefore a better forum for
 199 general discussions (such as reStructuredText syntax or the high-level
 200 Docutils project model), whereas the Docutils-specific lists are more
 201 focused on the implementation.
 202
 203 You can also access read-only archives of the mailing lists via Gmane:
 204 Docutils-users__, Docutils-develop__, Docutils-checkins__ and
 205 Doc-SIG__.
 206
 207 .. [#docutils-users] Due to overwhelming amounts of spam, the
 208    docutils-users@lists.sourceforge.net mailing list has been set up
 209    for subscriber posting only.  Non-subscribers who post to
 210    docutils-users will receive a message with "Subject: Your message
 211    to Docutils-users awaits moderator approval".  Legitimate messages
 212    are accepted and posted as soon as possible (a list administrator
 213    must verify the message manually).  If you'd like to subscribe to
 214    docutils-users, please visit
 215    <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
 216
 217 .. _FAQ:
 218 .. _Docutils FAQ: FAQ.html
 219 __ mailto:docutils-users@lists.sourceforge.net
 220 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
 221 __ http://mail.python.org/mailman/listinfo/doc-sig
 222 __ http://lists.sourceforge.net/lists/listinfo/docutils-develop
 223 __ http://lists.sourceforge.net/lists/listinfo/docutils-checkins
 224 __ http://news.gmane.org/gmane.text.docutils.user
 225 __ http://news.gmane.org/gmane.text.docutils.devel
 226 __ http://news.gmane.org/gmane.text.docutils.cvs
 227 __ http://news.gmane.org/gmane.comp.python.documentation
 228
 229
 230 The Sandbox
 231 ===========
 232
 233 The Sandbox__ is a place to play around, to try out and share ideas.
 234 It's a part of the CVS repository but it isn't distributed as part of
 235 Docutils releases (you can get a recent tarball from the `development
 236 snapshots`_).  Each developer who wants to play in it should create
 237 their own subdirectory (suggested name: SourceForge ID, or given name
 238 + family initial).
 239
 240 Please feel free to `visit the sandbox`__.
 241
 242 It's OK to make a mess in the Sandbox!  But please, play nice.
 243
 244 __
 245 __ sandbox/
 246
 247
 248 Sandbox Projects
 249 ----------------
 250
 251 Anyone is welcome to contribute to any of these projects.  Interested
 252 developers are welcome to take on any projects which appear to be
 253 dormant.  Please direct any email to
 254 docutils-develop@lists.sourceforge.net.
 255
 256 * ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope"
 257   application that is complete and ready to install.
 258
 259 * PySource_, by Tony Ibbs, is an experimental Python source Reader.
 260   In some form, it will soon become part of core Docutils.  There is
 261   some related code in David Goodger's sandbox (pysource_reader_) and
 262   a `Python Source Reader <docs/dev/pysource.html>`__ document.
 263
 264 * Docutils interface to PythonPoint_, also by Richard Jones, produces
 265   PDF presentations using ReportLabs.
 266
 267 * Engelbert Gruber has begun `LaTeX Writer`_ and `ManPage Writer`_ components.
 268
 269 * ? has taken over `ReportLabs/PDF Writer`_ components.
 270
 271 * Oliver Rutherfurd has begun a `DocBook Writer`_ component and
 272   `HT2HTML integration`_ component.
 273
 274 * Gunnar Schwant's DocFactory_ is a wxPython GUI application for
 275   Docutils.
 276
 277 * Aahz has begun an `OpenOffice.org Writer`_.
 278
 279 * Ian Bicking is working on code for a Wiki_.
 280
 281 * Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely
 282   on CSS (stylesheets).
 283
 284 * Beni Cherniavsky has written a generic `preprocessing module`_ for
 285   roles and/or directives and built preprocessors for TeX math for
 286   both LaTeX and HTML output on top of it.
 287
 288 * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
 289   to handle everything one might do with docutils.
 290
 291 .. _ZReST: sandbox/richard/ZReST/
 292 .. _PySource: sandbox/tibs/pysource/
 293 .. _pysource_reader: sandbox/davidg/pysource_reader/
 294 .. _PythonPoint: sandbox/richard/pythonpoint/
 295 .. _LaTeX Writer: sandbox/grubert/latex/
 296 .. _Manpage Writer: sandbox/grubert/man/
 297 .. _ReportLabs/PDF Writer: sandbox/dreamcatcher/rlpdf/
 298 .. _DocBook Writer: sandbox/oliverr/docbook/
 299 .. _HT2HTML integration: sandbox/oliverr/ht/
 300 .. _DocFactory: sandbox/gschwant/docfactory/doc/
 301 .. _OpenOffice.org Writer: sandbox/aahz/OO/
 302 .. _Wiki: sandbox/ianb/wiki/
 303 .. _simple HTML writer: sandbox/bbum/DocArticle/
 304 .. _preprocessing module: sandbox/cben/rolehack/
 305 .. _Makefile: sandbox/cben/make/
 306
 307
 308 Please Contribute!
 309 ==================
 310
 311 Please help this project succeed by contributing.  We're looking for
 312 all kinds of contributions: testing, ideas, code, bug reports,
 313 administration, tasty snacks, computer equipment, and large sums of
 314 money.  There's a `To Do list`_ full of interesting ideas awaiting a
 315 champion.  If you're interested in participating in any way, please
 316 `contact the project coordinator`__.
 317
 318 Please consider donating to Docutils: |donate|
 319
 320 __ mailto_
 321
 322
 323 Project Links
 324 =============
 325
 326 - `Project Summary page`__: `released files`__, `bug reports`__,
 327   patches__, `mailing lists`__, and news__.
 328 - `Docutils CVS repository`__
 329 - Project coordinator and architect: `David Goodger`_
 330 - Please direct discussions to the `Python Documentation Special
 331   Interest Group (Doc-SIG)`__: doc-sig@python.org.
 332 - Powered by |Python|__
 333 - Hosted by |SourceForge|__
 334
 335   __ http://sourceforge.net/projects/docutils/
 336   __ `project files page`_
 337   __ http://sourceforge.net/tracker/?group_id=38414&atid=422030
 338   __ http://sourceforge.net/tracker/?group_id=38414&atid=422032
 339   __ http://sourceforge.net/mail/?group_id=38414
 340   __ http://sourceforge.net/news/?group_id=38414
 341
 342   __ CVS_
 343
 344   __ Doc-SIG_
 345
 346   __ http://www.python.org/
 347   .. |Python| image:: PyBanner016.png
 348   .. :border: 0
 349
 350   __ http://sourceforge.net/
 351   .. |SourceForge| image::
 352      http://sourceforge.net/sflogo.php?group_id=38414
 353      :alt: SourceForge Logo
 354   .. :border: 0
 355
 356 .. _reStructuredText: rst.html
 357 .. _project files page:
 358    http://sourceforge.net/project/showfiles.php?group_id=38414
 359 .. _Anonymous CVS access: http://sourceforge.net/cvs/?group_id=38414
 360 .. _CVS:
 361 .. _browse the CVS repository:
 362    http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/
 363 .. _To Do list: docs/dev/todo.html
 364 .. _README: README.html
 365 .. _HISTORY: HISTORY.html
 366 .. _COPYING: COPYING.html
 367 .. _BUGS: BUGS.html
 368 .. _mailto:
 369 .. _David Goodger: mailto:goodger@users.sourceforge.net
 370 .. _Doc-SIG: http://www.python.org/sigs/doc-sig/
 371
 372 .. _PEPs:
 373 .. _PEPs (Python Enhancement Proposals): http://www.python.org/peps/
 374
 375 .. _latest project release package:
 376    http://prdownloads.sourceforge.net/docutils/docutils-0.3.5.tar.gz?download
 377
 378 \f
 379 ..
 380    Local Variables:
 381    mode: indented-text
 382    indent-tabs-mode: nil
 383    sentence-end-double-space: t
 384    fill-column: 70
 385    End: