==========================================
Docutils Project Documentation Overview
==========================================
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2022-06-13 14:05:18 +0200 (Mo, 13. Jun 2022) $
:Revision: $Revision: 9069 $
: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:
Generated by dwww version 1.15 on Wed Jun 26 01:49:17 CEST 2024.