========================================== Docutils_ Project Documentation Overview ========================================== :Author: David Goodger :Contact: docutils-develop@lists.sourceforge.net :Date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $ :Revision: $Revision: 7302 $ :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: http://docutils.sourceforge.net/ .. _Docutils distribution: http://docutils.sourceforge.net/#download .. 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. :README.txt_: Project overview: quick-start, requirements, installation, and usage. :COPYING.txt_: Conditions for Docutils redistribution, with links to licenses. :FAQ.txt_: Docutils Frequently Asked Questions. If you have a question or issue, there's a good chance it's already answered here. :BUGS.txt_: A list of known bugs, and how to report a bug. :RELEASE-NOTES.txt_: Summary of the major changes in recent releases. :HISTORY.txt_: Detailed change history log. :THANKS.txt_: Acknowledgements. .. _README.txt: ../README.html .. _BUGS.txt: ../BUGS.html .. _COPYING.txt: ../COPYING.html .. _Docutils FAQ: .. _FAQ.txt: ../FAQ.html .. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html .. _HISTORY.txt: ../HISTORY.html .. _THANKS.txt: ../THANKS.html .. _user: ``user/``: Introductory & Tutorial Material for End-Users ========================================================= Docutils-general: * `Docutils Front-End Tools `__ * `Docutils Configuration `__ * `Docutils Mailing Lists `__ * `Docutils Link List `__ Writer-specific: * `Easy Slide Shows With reStructuredText & S5 `__ * `Docutils LaTeX Writer `__ * `Docutils ODF/OpenOffice/odt Writer `__ `reStructuredText `_: * `A ReStructuredText Primer (HTML) `__ (or `text source `__) * `Quick reStructuredText `__ (user reference) * `reStructuredText Cheat Sheet `__ (text only; 1 page for syntax, 1 page directive & role reference) * `reStructuredText Demonstration `_ (a demonstration of most reStructuredText features; you can also have a look at the `text source `__) Editor support: * `Emacs support for reStructuredText `_ .. _ref: ``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 `__ (incomplete) * `Docutils Transforms `__ * `Docutils Generic DTD `__ * `OASIS XML Exchange Table Model Declaration Module `__ (CALS tables DTD module) Although not in the "ref" directory, `PEP 258`_ is a must-read reference for any Docutils developer. reStructuredText_: * `An Introduction to reStructuredText `__ (includes the `Goals `__ and `History `__ of reStructuredText) * `reStructuredText Markup Specification `__ * `reStructuredText Directives `__ * `reStructuredText Interpreted Text Roles `__ * `reStructuredText Standard Definition Files `_ Prehistoric: * `Setext Documents Mirror `__ .. _peps: ``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`_ may not be current, whereas the local versions are. __ peps/pep-0256.html __ http://www.python.org/peps/pep-0256.html __ peps/pep-0257.html __ http://www.python.org/peps/pep-0257.html .. _PEP 258: __ peps/pep-0258.html __ http://www.python.org/peps/pep-0258.html __ peps/pep-0287.html __ http://www.python.org/peps/pep-0287.html .. _master repository: http://www.python.org/peps/ .. _api: ``api/``: API Reference Material for Client-Developers ====================================================== * `The Docutils Publisher `__ * `Inside A Docutils Command-Line Front-End Tool `__ * `Docutils Runtime Settings `__ * (`Docutils Transforms `__ should be moved here) `PEP 258`_ is an overview of the architecture of Docutils. .. _howto: ``howto/``: Instructions for Developers ======================================= * **Security:** `Deploying Docutils Securely `__ * `Writing HTML (CSS) Stylesheets for Docutils `__ * `Docutils Internationalization `__ * `Creating reStructuredText Directives `__ * `Creating reStructuredText Interpreted Text Roles `__ .. _dev: ``dev/``: Development Notes and Plans for Core-Developers ========================================================= Docutils-general: * `Docutils Hacker's Guide `__ * `Docutils Distributor's Guide `__ * `Docutils To Do List `__ * `Docutils Project Policies `__ * `Docutils Web Site `__ * `Docutils Release Procedure `__ * `The Docutils Subversion Repository `__ * `Docutils Testing `__ * `Docstring Semantics `__ (incomplete) * `Python Source Reader `_ (incomplete) * `Docutils Python DTD `_ (experimental) * `Plan for Enthought API Documentation Tool `_ * `Enthought API Documentation Tool RFP `_ reStructuredText_: * `A Record of reStructuredText Syntax Alternatives `__ * `Problems With StructuredText `__ .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: