README.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394
  1. =======================
  2. README: Docutils 0.14
  3. =======================
  4. :Author: David Goodger
  5. :Contact: goodger@python.org
  6. :Date: $Date: 2017-08-03 11:03:32 +0200 (Do, 03 Aug 2017) $
  7. :Web site: http://docutils.sourceforge.net/
  8. :Copyright: This document has been placed in the public domain.
  9. .. contents::
  10. Quick-Start
  11. ===========
  12. This is for those who want to get up & running quickly.
  13. 1. Docutils requires Python (version 2.4 or later), available from
  14. http://www.python.org/
  15. See Requirements_ below for details.
  16. 2. Use the latest Docutils code. Get the code from the `Subversion
  17. repository`_ or from the snapshot:
  18. http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar
  19. See `Releases & Snapshots`_ below for details.
  20. 3. Unpack the tarball in a temporary directory (**not** directly in
  21. Python's ``site-packages``), go to the directory created by expanding
  22. the archive, and run ``setup.py install``. On
  23. Windows systems it may be sufficient to double-click ``install.py``.
  24. See Installation_ below for details.
  25. 4. Use the front-end scripts to convert reStructuredText documents.
  26. Try for example::
  27. rst2html.py FAQ.txt FAQ.html (Unix)
  28. python tools/rst2html.py FAQ.txt FAQ.html (Windows)
  29. See Usage_ below for details.
  30. Purpose
  31. =======
  32. The purpose of the Docutils project is to create a set of tools for
  33. processing plaintext documentation into useful formats, such as HTML,
  34. XML, and LaTeX. Support for the following sources has been
  35. implemented:
  36. * Standalone files.
  37. * `PEPs (Python Enhancement Proposals)`_.
  38. Support for the following sources is planned:
  39. * Inline documentation from Python modules and packages, extracted
  40. with namespace context.
  41. * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  42. * Wikis, with global reference lookups of "wiki links".
  43. * Compound documents, such as multiple chapter files merged into a
  44. book.
  45. * And others as discovered.
  46. .. _PEPs (Python Enhancement Proposals):
  47. http://www.python.org/peps/pep-0012.html
  48. Releases & Snapshots
  49. ====================
  50. While we are trying to follow a "release early & often" policy,
  51. features are added frequently. Since the code in the Subversion
  52. repository is usually in a bug-free state, we recommend that you use
  53. a current snapshot.
  54. To get a snapshot, go to the code page and click the download snapshot
  55. button:
  56. * Docutils code, documentation, front-end tools, and tests:
  57. https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
  58. * Sandbox (experimental, contributed code):
  59. https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
  60. To keep up to date on the latest developments, download fresh copies of
  61. the snapshots regularly or use a working copy of the
  62. `Subversion repository`_.
  63. .. _Subversion repository: docs/dev/repository.html
  64. Requirements
  65. ============
  66. To run the code, Python_ must be installed.
  67. Docutils is compatible with Python versions from 2.4 up to 2.7 and
  68. versions 3.1 to 3.5 (cf. `Python 3 compatibility`_).
  69. Docutils uses the following packages for enhanced functionality, if they are
  70. installed:
  71. * The `Python Imaging Library`_, or PIL, is used for some image
  72. manipulation operations.
  73. * The `Pygments`_ syntax highlighter is used for content of `code`
  74. directives and roles.
  75. .. _Python: http://www.python.org/.
  76. .. _Python Imaging Library: http://www.pythonware.com/products/pil/
  77. .. _Pygments: http://pygments.org/
  78. Python 3 compatibility
  79. ----------------------
  80. The Docutils codebase is written for Python 2 and uses "on-demand"
  81. translation for `porting to Python 3`_.
  82. * The `setup.py` script generates Python 3 compatible sources in
  83. ``build/`` and tests in ``tests3/`` sub-directories during
  84. installation_ with Python 3.
  85. * The scripts in the ``tools/`` sub-directory work with all supported
  86. Python versions without conversion.
  87. * To convert the sources without installing (e.g. for testing), run
  88. ``python3 setup.py build``.
  89. * When editing the source, do changes on the Python 2 versions of the
  90. files and re-run the build command.
  91. .. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html
  92. Project Files & Directories
  93. ===========================
  94. * README.txt: You're reading it.
  95. * COPYING.txt: Public Domain Dedication and copyright details for
  96. non-public-domain files (most are PD).
  97. * FAQ.txt: Frequently Asked Questions (with answers!).
  98. * RELEASE-NOTES.txt: Summary of the major changes in recent releases.
  99. * HISTORY.txt: A detailed change log, for the current and all previous
  100. project releases.
  101. * BUGS.txt: Known bugs, and how to report a bug.
  102. * THANKS.txt: List of contributors.
  103. * setup.py: Installation script. See "Installation" below.
  104. * install.py: Quick & dirty installation script. Just run it. For
  105. any kind of customization or help though, setup.py must be used.
  106. * docutils: The project source directory, installed as a Python
  107. package.
  108. * docs: The project documentation directory. Read ``docs/index.txt``
  109. for an overview.
  110. * docs/user: The project user documentation directory. Contains the
  111. following documents, among others:
  112. - docs/user/tools.txt: Docutils Front-End Tools
  113. - docs/user/latex.txt: Docutils LaTeX Writer
  114. - docs/user/rst/quickstart.txt: A ReStructuredText Primer
  115. - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)
  116. * docs/ref: The project reference directory.
  117. ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
  118. reference.
  119. * licenses: Directory containing copies of license files for
  120. non-public-domain files.
  121. * tools: Directory for Docutils front-end tools. See
  122. ``docs/user/tools.txt`` for documentation.
  123. * test: Unit tests. Not required to use the software, but very useful
  124. if you're planning to modify it. See `Running the Test Suite`_
  125. below.
  126. Generated directories when installing under Python 3:
  127. * build: Converted sources.
  128. * test3: Converted tests.
  129. Installation
  130. ============
  131. The first step is to expand the ``.tgz`` archive in a temporary
  132. directory (**not** directly in Python's ``site-packages``). It
  133. contains a distutils setup file "setup.py". OS-specific installation
  134. instructions follow.
  135. GNU/Linux, BSDs, Unix, Mac OS X, etc.
  136. -------------------------------------
  137. 1. Open a shell.
  138. 2. Go to the directory created by expanding the archive::
  139. cd <archive_directory_path>
  140. 3. Install the package (you may need root permissions to complete this
  141. step)::
  142. su
  143. (enter admin password)
  144. python setup.py install
  145. If the python executable isn't on your path, you'll have to specify
  146. the complete path, such as ``/usr/local/bin/python``.
  147. To install for a specific Python version, use this version in the
  148. setup call, e.g. ::
  149. python3.1 setup.py install
  150. To install for different Python versions, repeat step 3 for every
  151. required version. The last installed version will be used in the
  152. `shebang line`_ of the ``rst2*.py`` wrapper scripts.
  153. .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
  154. Windows
  155. -------
  156. Just double-click ``install.py``. If this doesn't work, try the
  157. following:
  158. 1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
  159. calling it these days).
  160. 2. Go to the directory created by expanding the archive::
  161. cd <archive_directory_path>
  162. 3. Install the package::
  163. <path_to_python.exe>\python setup.py install
  164. To install for a specific python version, specify the Python
  165. executable for this version.
  166. To install for different Python versions, repeat step 3 for every
  167. required version.
  168. Optional steps:
  169. * `running the test suite`_
  170. * `converting the documentation`_
  171. Usage
  172. =====
  173. There are many front-end tools in the unpacked "tools" subdirectory.
  174. Installation under Unix places copies in the PATH.
  175. You may want to begin with the "rst2html.py" front-end tool. Most
  176. tools take up to two arguments, the source path and destination path,
  177. with STDIN and STDOUT being the defaults. Use the "--help" option to
  178. the front-end tools for details on options and arguments. See
  179. Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
  180. The package modules are continually growing and evolving. The
  181. ``docutils.statemachine`` module is usable independently. It contains
  182. extensive inline documentation (in reStructuredText format of course).
  183. Contributions are welcome!
  184. Converting the documentation
  185. ============================
  186. After unpacking and installing the Docutils package, the following
  187. shell commands will generate HTML for all included documentation::
  188. cd <archive_directory_path>/tools
  189. ./buildhtml.py ../
  190. On Windows systems, type::
  191. cd <archive_directory_path>\tools
  192. python buildhtml.py ..
  193. The final directory name of the ``<archive_directory_path>`` is
  194. "docutils" for snapshots. For official releases, the directory may be
  195. called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
  196. Alternatively::
  197. cd <archive_directory_path>
  198. tools/buildhtml.py --config=tools/docutils.conf (Unix)
  199. python tools\buildhtml.py --config=tools\docutils.conf (Windows)
  200. Some files may generate system messages (warnings and errors). The
  201. ``docs/user/rst/demo.txt`` file (under the archive directory) contains
  202. five intentional errors. (They test the error reporting mechanism!)
  203. Running the Test Suite
  204. ======================
  205. The test suite is documented in `Docutils Testing`_ (docs/dev/testing.txt).
  206. To run the entire test suite, open a shell and use the following
  207. commands::
  208. cd <archive_directory_path>/test
  209. ./alltests.py
  210. Under Windows, type::
  211. cd <archive_directory_path>\test
  212. python alltests.py
  213. For testing with Python 3 use the converted test suite::
  214. cd <archive_directory_path>/test3
  215. python3 alltests.py
  216. You should see a long line of periods, one for each test, and then a
  217. summary like this::
  218. Ran 1111 tests in 24.653s
  219. OK
  220. Elapsed time: 26.189 seconds
  221. The number of tests will grow over time, and the times reported will
  222. depend on the computer running the tests. The difference between the
  223. two times represents the time required to set up the tests (import
  224. modules, create data structures, etc.).
  225. If any of the tests fail, please `open a bug report`_ or `send an email`_
  226. (see `Bugs <BUGS.html>`_).
  227. Please include all relevant output, information about your operating
  228. system, Python version, and Docutils version. To see the Docutils
  229. version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
  230. with the ``--version`` option, e.g.::
  231. cd ../tools
  232. ./quicktest.py --version
  233. Windows users type these commands::
  234. cd ..\tools
  235. python quicktest.py --version
  236. .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
  237. .. _open a bug report:
  238. http://sourceforge.net/p/docutils/bugs/
  239. .. _send an email: mailto:docutils-users@lists.sourceforge.net
  240. ?subject=Test%20suite%20failure
  241. .. _web interface: https://sourceforge.net/p/docutils/mailman/
  242. Getting Help
  243. ============
  244. If you have questions or need assistance with Docutils or
  245. reStructuredText, please post a message to the Docutils-users_ mailing
  246. list.
  247. .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
  248. ..
  249. Local Variables:
  250. mode: indented-text
  251. indent-tabs-mode: nil
  252. sentence-end-double-space: t
  253. fill-column: 70
  254. End: