===================================
 Docutils: Documentation Utilities
===================================
---------------------------------------------------------
 Written in Python, for General- and Special-Purpose Use
---------------------------------------------------------

Docutils is an open-source text processing system for processing
plaintext documentation into useful formats, such as HTML, LaTeX,
man-pages, OpenDocument, or XML.
It includes reStructuredText_, the easy to read, easy to use,
what-you-see-is-what-you-get plaintext markup language.

----------------------------------------------------------------------


Overview
========

**To get up & running quickly**, see the Quick-Start_ section of the
README_ file. The only requirement_ for running Docutils is Python_.

All **documentation** can be reached from the `Project Documentation
Overview`_. If something is unclear or missing, ask at the
docutils-users_ mailing list.

The |sourceforge| `project page`_ has links to the tracker, mailing
lists, and code repository.

All **discussion** about Docutils takes place on the `mailing lists`_.

To the developers of an open source project, **feedback** is a great
motivator and is very welcome.  We also rely on feedback for
determining what features to implement.  Thus, if you tell us what you
need, we may help!  Please post any feedback to the
docutils-users_ mailing list.

If you find a **bug**, please `file a bug report`_ or mail to the
docutils-users_ mailing list.

We welcome all kinds of **contributions**.  There's a `To Do list`_ full
of ideas awaiting a champion.  If you have any questions regarding how to
extend Docutils, please feel free to ask on the docutils-develop_ mailing
list. **Patch** submissions should be filed in the `patch tracker`_
(preferred) or sent to docutils-develop_.

Download
========

`Release packages`_ can be downloaded from PyPI_. They are mostly intended
for distributors.  See the `release notes`_ for a list of changes since the
previous release.

We recommend that you use a snapshot_ [#snapshots]_ from `Docutils' Subversion
repository`_. The snapshots usually contain *more features* and *fewer bugs*
than the "official" releases |---| they're not only for developers!

.. [#snapshots] Snapshots are created on-demand by Sourceforge.  You can
   download a snapshot of the complete `trunk directory`_ (docutils,
   sandbox_, prest/perl and web) or any sub-directory. Browse to the
   desired directory and click the "Download Snapshot" button.

----------------------------------------------------------------------

.. class:: credits

Web site, tracker, mailing lists, and repository hosted by |SourceForge|_.
Powered by |Python|_.

.. |---| unicode:: U+02014 .. em dash
   :trim:

.. _snapshot:
   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
.. _trunk directory: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/
.. _patch tracker: https://sourceforge.net/p/docutils/patches/
.. _file a bug report: BUGS.html#how-to-report-a-bug
.. _mailing lists: docs/user/mailing-lists.html
.. _docutils-users: docs/user/mailing-lists.html#docutils-users
.. _docutils-develop: docs/user/mailing-lists.html#docutils-develop
.. _sandbox: sandbox/README.html
.. _reStructuredText: rst.html
.. _project page: https://sourceforge.net/p/docutils
.. _To Do list: docs/dev/todo.html
.. _README: README.html
.. _Quick-Start: README.html#quick-start
.. _Project Documentation Overview: docs/index.html
.. _Docutils' Subversion repository: docs/dev/repository.html
.. _requirement: README.html#requirements
.. _release packages: https://pypi.org/project/docutils/#files
.. _PyPI: https://pypi.org
.. _release notes: RELEASE-NOTES.html

.. |SourceForge| image::
   https://sourceforge.net/sflogo.php?group_id=38414
   :alt: SourceForge
   :align: middle
   :height: 1.5em
.. _SourceForge: https://sourceforge.net/

.. |Python| image:: python.png
   :alt: Python
   :align: middle
   :height: 1em
.. _Python: https://www.python.org/



..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: