index.txt 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239
  1. ==========================================
  2. Docutils_ Project Documentation Overview
  3. ==========================================
  4. :Author: David Goodger
  5. :Contact: docutils-develop@lists.sourceforge.net
  6. :Date: $Date: 2016-01-13 22:09:13 +0100 (Mi, 13 Jan 2016) $
  7. :Revision: $Revision: 7933 $
  8. :Copyright: This document has been placed in the public domain.
  9. The latest working documents may be accessed individually below, or
  10. from the ``docs`` directory of the `Docutils distribution`_.
  11. .. _Docutils: http://docutils.sourceforge.net/
  12. .. _Docutils distribution: http://docutils.sourceforge.net/#download
  13. .. contents::
  14. Docutils Stakeholders
  15. =====================
  16. Docutils stakeholders can be categorized in several groups:
  17. 1. End-users: users of reStructuredText and the Docutils tools.
  18. Although some are developers (e.g. Python developers utilizing
  19. reStructuredText for docstrings in their source), many are not.
  20. 2. Client-developers: developers using Docutils as a library,
  21. programmers developing *with* Docutils.
  22. 3. Component-developers: those who implement application-specific
  23. components, directives, and/or roles, separately from Docutils.
  24. 4. Core-developers: developers of the Docutils codebase and
  25. participants in the Docutils project community.
  26. 5. Re-implementers: developers of alternate implementations of
  27. Docutils.
  28. There's a lot of overlap between these groups. Most (perhaps all)
  29. core-developers, component-developers, client-developers, and
  30. re-implementers are also end-users. Core-developers are also
  31. client-developers, and may also be component-developers in other
  32. projects. Component-developers are also client-developers.
  33. Project Fundamentals
  34. ====================
  35. These files are for all Docutils stakeholders. They are kept at the
  36. top level of the Docutils project directory.
  37. :README.txt_: Project overview: quick-start, requirements,
  38. installation, and usage.
  39. :COPYING.txt_: Conditions for Docutils redistribution, with links to
  40. licenses.
  41. :FAQ.txt_: Docutils Frequently Asked Questions. If you have a
  42. question or issue, there's a good chance it's already
  43. answered here.
  44. :BUGS.txt_: A list of known bugs, and how to report a bug.
  45. :RELEASE-NOTES.txt_: Summary of the major changes in recent releases.
  46. :HISTORY.txt_: Detailed change history log.
  47. :THANKS.txt_: Acknowledgements.
  48. .. _README.txt: ../README.html
  49. .. _BUGS.txt: ../BUGS.html
  50. .. _COPYING.txt: ../COPYING.html
  51. .. _Docutils FAQ:
  52. .. _FAQ.txt: ../FAQ.html
  53. .. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html
  54. .. _HISTORY.txt: ../HISTORY.html
  55. .. _THANKS.txt: ../THANKS.html
  56. .. _user:
  57. ``user/``: Introductory & Tutorial Material for End-Users
  58. =========================================================
  59. Docutils-general:
  60. * `Docutils Front-End Tools <user/tools.html>`__
  61. * `Docutils Configuration <user/config.html>`__
  62. * `Docutils Mailing Lists <user/mailing-lists.html>`__
  63. * `Docutils Link List <user/links.html>`__
  64. Writer-specific:
  65. * `Docutils HTML writers <user/html.html>`__
  66. * `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
  67. * `Docutils LaTeX Writer <user/latex.html>`__
  68. * `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__
  69. `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
  70. * `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
  71. `text source <user/rst/quickstart.txt>`__)
  72. * `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
  73. * `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
  74. only; 1 page for syntax, 1 page directive & role reference)
  75. * `reStructuredText Demonstration <user/rst/demo.html>`_ (a
  76. demonstration of most reStructuredText features; you can also have a
  77. look at the `text source <user/rst/demo.txt>`__)
  78. Editor support:
  79. * `Emacs support for reStructuredText <user/emacs.html>`_
  80. .. _ref:
  81. ``ref/``: Reference Material for All Groups
  82. ===========================================
  83. Many of these files began as developer specifications, but now that
  84. they're mature and used by end-users and client-developers, they have
  85. become reference material. Successful specs evolve into refs.
  86. Docutils-general:
  87. * `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
  88. * `Docutils Transforms <ref/transforms.html>`__
  89. * `Docutils Generic DTD <ref/docutils.dtd>`__
  90. * `OASIS XML Exchange Table Model Declaration Module
  91. <ref/soextblx.dtd>`__ (CALS tables DTD module)
  92. Although not in the "ref" directory, `PEP 258`_ is a must-read
  93. reference for any Docutils developer.
  94. reStructuredText_:
  95. * `An Introduction to reStructuredText <ref/rst/introduction.html>`__
  96. (includes the `Goals <ref/rst/introduction.html#goals>`__ and
  97. `History <ref/rst/introduction.html#history>`__ of reStructuredText)
  98. * `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
  99. * `reStructuredText Directives <ref/rst/directives.html>`__
  100. * `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
  101. * `reStructuredText Standard Definition Files
  102. <ref/rst/definitions.html>`_
  103. Prehistoric:
  104. * `Setext Documents Mirror
  105. <http://docutils.sourceforge.net/mirror/setext.html>`__
  106. .. _peps:
  107. ``peps/``: Python Enhancement Proposals
  108. =======================================
  109. * `PEP 256: Docstring Processing System Framework`__ is a high-level
  110. generic proposal. [`PEP 256`__ in the `master repository`_]
  111. * `PEP 257: Docstring Conventions`__ addresses docstring style and
  112. touches on content. [`PEP 257`__ in the `master repository`_]
  113. * `PEP 258: Docutils Design Specification`__ is an overview of the
  114. architecture of Docutils. It documents design issues and
  115. implementation details. [`PEP 258`__ in the `master repository`_]
  116. * `PEP 287: reStructuredText Docstring Format`__ proposes a standard
  117. markup syntax. [`PEP 287`__ in the `master repository`_]
  118. Please note that PEPs in the `master repository`_ may not be current,
  119. whereas the local versions are.
  120. __ peps/pep-0256.html
  121. __ http://www.python.org/peps/pep-0256.html
  122. __ peps/pep-0257.html
  123. __ http://www.python.org/peps/pep-0257.html
  124. .. _PEP 258:
  125. __ peps/pep-0258.html
  126. __ http://www.python.org/peps/pep-0258.html
  127. __ peps/pep-0287.html
  128. __ http://www.python.org/peps/pep-0287.html
  129. .. _master repository: http://www.python.org/peps/
  130. .. _api:
  131. ``api/``: API Reference Material for Client-Developers
  132. ======================================================
  133. * `The Docutils Publisher <api/publisher.html>`__
  134. * `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__
  135. * `Docutils Runtime Settings <api/runtime-settings.html>`__
  136. * (`Docutils Transforms <ref/transforms.html>`__ should be moved here)
  137. `PEP 258`_ is an overview of the architecture of Docutils.
  138. .. _howto:
  139. ``howto/``: Instructions for Developers
  140. =======================================
  141. * **Security:** `Deploying Docutils Securely <howto/security.html>`__
  142. * `Writing HTML (CSS) Stylesheets for Docutils
  143. <howto/html-stylesheets.html>`__
  144. * `Docutils Internationalization <howto/i18n.html>`__
  145. * `Creating reStructuredText Directives <howto/rst-directives.html>`__
  146. * `Creating reStructuredText Interpreted Text Roles
  147. <howto/rst-roles.html>`__
  148. .. _dev:
  149. ``dev/``: Development Notes and Plans for Core-Developers
  150. =========================================================
  151. Docutils-general:
  152. * `Docutils Hacker's Guide <dev/hacking.html>`__
  153. * `Docutils Distributor's Guide <dev/distributing.html>`__
  154. * `Docutils To Do List <dev/todo.html>`__
  155. * `Docutils Project Policies <dev/policies.html>`__
  156. * `Docutils Web Site <dev/website.html>`__
  157. * `Docutils Release Procedure <dev/release.html>`__
  158. * `The Docutils Subversion Repository <dev/repository.html>`__
  159. * `Docutils Testing <dev/testing.html>`__
  160. * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
  161. * `Python Source Reader <dev/pysource.html>`_ (incomplete)
  162. * `Docutils Python DTD <dev/pysource.dtd>`_ (experimental)
  163. * `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
  164. * `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_
  165. reStructuredText_:
  166. * `A Record of reStructuredText Syntax Alternatives
  167. <dev/rst/alternatives.html>`__
  168. * `Problems With StructuredText <dev/rst/problems.html>`__
  169. ..
  170. Local Variables:
  171. mode: indented-text
  172. indent-tabs-mode: nil
  173. sentence-end-double-space: t
  174. fill-column: 70
  175. End: