==========================================
 Docutils Project Documentation Overview
==========================================

:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This document has been placed in the public domain.

The latest working documents may be accessed individually below, or
from the ``docs`` directory of the `Docutils distribution`_.

.. _Docutils: https://docutils.sourceforge.io/
.. _Docutils distribution: https://docutils.sourceforge.io/#download

.. header::
   Docutils_ | Overview | About__ | Users__ | Reference__ | Developers__

__ `project fundamentals`_
__ user_
__ ref_
__ howto_


.. contents::


Docutils Stakeholders
=====================

Docutils stakeholders can be categorized in several groups:

1. End-users: users of reStructuredText and the Docutils tools.
   Although some are developers (e.g. Python developers utilizing
   reStructuredText for docstrings in their source), many are not.

2. Client-developers: developers using Docutils as a library,
   programmers developing *with* Docutils.

3. Component-developers: those who implement application-specific
   components, directives, and/or roles, separately from Docutils.

4. Core-developers: developers of the Docutils codebase and
   participants in the Docutils project community.

5. Re-implementers: developers of alternate implementations of
   Docutils.

There's a lot of overlap between these groups.  Most (perhaps all)
core-developers, component-developers, client-developers, and
re-implementers are also end-users.  Core-developers are also
client-developers, and may also be component-developers in other
projects.  Component-developers are also client-developers.


Project Fundamentals
====================

These files are for all Docutils stakeholders.  They are kept at the
top level of the Docutils project directory.

.. class:: narrow run-in
    
:README_:  Project overview: quick-start, requirements,
           installation, and usage.
:COPYING_: Conditions for Docutils redistribution, with links to
           licenses.
:FAQ_:     Docutils Frequently Asked Questions.  If you have a
           question or issue, there's a good chance it's already
           answered here.
:BUGS_:    A list of known bugs, and how to report a bug.
:RELEASE-NOTES_: Summary of the major changes in recent releases and
           notice of future incompatible changes.
:HISTORY_: Detailed change history log.
:THANKS_:  Acknowledgements.

.. _README: ../README.html
.. _BUGS: ../BUGS.html
.. _COPYING: ../COPYING.html
.. _Docutils FAQ:
.. _FAQ: ../FAQ.html
.. _RELEASE-NOTES: ../RELEASE-NOTES.html
.. _HISTORY: ../HISTORY.html
.. _THANKS: ../THANKS.html


.. _user:

Introductory & Tutorial Material for End-Users
==============================================

Docutils-general:
  * `Docutils Front-End Tools <user/tools.html>`__
  * `Docutils Configuration <user/config.html>`__
  * `Docutils Mailing Lists <user/mailing-lists.html>`__
  * `Docutils Link List <user/links.html>`__

Writer-specific:
  * `Docutils HTML Writers <user/html.html>`__
  * `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
  * `Docutils LaTeX Writer <user/latex.html>`__
  * `Man Page Writer for Docutils <user/manpage.html>`__
  * `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__

`reStructuredText <https://docutils.sourceforge.io/rst.html>`_:
  * `A ReStructuredText Primer <user/rst/quickstart.html>`__
    (see also the `text source <user/rst/quickstart.txt>`__)
  * `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
  * `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
    only; 1 page for syntax, 1 page directive & role reference)
  * `Demonstration <user/rst/demo.html>`_ 
    of most reStructuredText features
    (see also the `text source <user/rst/demo.txt>`__)

Editor support:
  * `Emacs support for reStructuredText <user/emacs.html>`_


.. _ref:

Reference Material for All Groups
=================================

Many of these files began as developer specifications, but now that
they're mature and used by end-users and client-developers, they have
become reference material.  Successful specs evolve into refs.

Docutils-general:
  * `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
  * `Docutils Generic DTD <ref/docutils.dtd>`__
  * `OASIS XML Exchange Table Model Declaration Module
    <ref/soextblx.dtd>`__ (CALS tables DTD module)
  * `Docutils Design Specification`_ (PEP 258)

reStructuredText_:
  * `An Introduction to reStructuredText <ref/rst/introduction.html>`__
    (includes the `Goals <ref/rst/introduction.html#goals>`__ and
    `History <ref/rst/introduction.html#history>`__ of reStructuredText)
  * `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
  * `reStructuredText Directives <ref/rst/directives.html>`__
  * `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
  * `reStructuredText Standard Definition Files
    <ref/rst/definitions.html>`_
  * `LaTeX syntax for mathematics <ref/rst/mathematics.html>`__
    (syntax used in "math" directive and role)

.. _peps:

Python Enhancement Proposals
  * `PEP 256: Docstring Processing System Framework`__ is a high-level
    generic proposal.  [:PEP:`256` in the `master repository`_]
  * `PEP 257: Docstring Conventions`__ addresses docstring style and
    touches on content.  [:PEP:`257` in the `master repository`_]
  * `PEP 258: Docutils Design Specification`__ is an overview of the
    architecture of Docutils.  It documents design issues and
    implementation details.  [:PEP:`258` in the `master repository`_]
  * `PEP 287: reStructuredText Docstring Format`__ proposes a standard
    markup syntax.  [:PEP:`287` in the `master repository`_]
  
  Please note that PEPs in the `master repository`_ developed
  independent from the local versions after submission.

  __ peps/pep-0256.html
  __ peps/pep-0257.html
  .. _PEP 258:
  .. _Docutils Design Specification:
  __ peps/pep-0258.html
  __ peps/pep-0287.html
  .. _master repository: https://peps.python.org

Prehistoric:
  `Setext Documents Mirror`__
  
  __ https://docutils.sourceforge.io/mirror/setext.html


.. _api:

API Reference Material for Client-Developers
============================================

* `The Docutils Publisher <api/publisher.html>`__
* `Docutils Runtime Settings <api/runtime-settings.html>`__
* `Docutils Transforms <api/transforms.html>`__ 
  
The `Docutils Design Specification`_ (PEP 258) is a must-read for any
Docutils developer.


.. _howto:

Instructions for Developers
===========================

:Security: `Deploying Docutils Securely <howto/security.html>`__

* `Inside A Docutils Command-Line Front-End Tool <howto/cmdline-tool.html>`__
* `Writing HTML (CSS) Stylesheets for Docutils
  <howto/html-stylesheets.html>`__
* `Docutils Internationalization <howto/i18n.html>`__
* `Creating reStructuredText Directives <howto/rst-directives.html>`__
* `Creating reStructuredText Interpreted Text Roles
  <howto/rst-roles.html>`__


.. _dev:

Development Notes and Plans for Core-Developers
===============================================

Docutils-general:
  * `Docutils Hacker's Guide <dev/hacking.html>`__
  * `Docutils Distributor's Guide <dev/distributing.html>`__
  * `Docutils To Do List <dev/todo.html>`__
  * `Docutils Project Policies <dev/policies.html>`__
  * `Docutils Web Site <dev/website.html>`__
  * `Docutils Release Procedure <dev/release.html>`__
  * `The Docutils Subversion Repository <dev/repository.html>`__
  * `Docutils Testing <dev/testing.html>`__
  * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
  * `Python Source Reader <dev/pysource.html>`_ (incomplete)
  * `Docutils Python DTD <dev/pysource.dtd>`_
  * `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
  * `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_

reStructuredText_:
  * `A Record of reStructuredText Syntax Alternatives
    <dev/rst/alternatives.html>`__
  * `Problems With StructuredText <dev/rst/problems.html>`__

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