README.txt

   1 ==================
   2  README: Docutils
   3 ==================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@users.sourceforge.net
   7 :Date: $Date$
   8 :Web site: http://docutils.sourceforge.net/
   9
  10 .. contents::
  11
  12
  13 Thank you for downloading the Python Docutils project archive.  As
  14 this is a work in progress, please check the project website for
  15 updated working files.  This project should be considered highly
  16 experimental; APIs are subject to change at any time.
  17
  18 The purpose of the Docutils project is to create a set of tools for
  19 processing plaintext documentation into useful formats, such as HTML,
  20 XML, and TeX.  Support for the following sources has been implemented:
  21
  22 * Standalone files.
  23
  24 * `PEPs (Python Enhancement Proposals)`_.
  25
  26 Support for the following sources is planned:
  27
  28 * Inline documentation from Python modules and packages, extracted
  29   with namespace context.  **This is the focus of the current
  30   development effort.**
  31
  32 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
  33
  34 * Wikis, with global reference lookups of "wiki links".
  35
  36 * Compound documents, such as multiple chapter files merged into a
  37   book.
  38
  39 * And others as discovered.
  40
  41 .. _PEPs (Python Enhancement Proposals):
  42    http://www.python.org/peps/pep-0012.html
  43
  44
  45 Releases & Snapshots
  46 ====================
  47
  48 Putting together an official "Release" of Docutils is a significant
  49 effort, so it isn't done that often.  In the meantime, the CVS
  50 snapshots always contain the latest code and documentation, usually
  51 updated within an hour of changes being committed to the repository,
  52 and usually bug-free:
  53
  54 * Snapshot of Docutils code, tests, documentation, and
  55   specifications: http://docutils.sf.net/docutils-snapshot.tgz
  56
  57 * Snapshot of the Sandbox (experimental, contributed code):
  58   http://docutils.sf.net/docutils-sandbox-snapshot.tgz
  59
  60 * Snapshot of web files (the files that generate the web site):
  61   http://docutils.sf.net/docutils-web-snapshot.tgz
  62
  63 To keep up to date on the latest developments, download fresh copies
  64 of the snapshots regularly.  New functionality is being added weekly,
  65 sometimes daily.  (There's also the CVS repository, and a mailing list
  66 for CVS messages.  See the web site [address above] or spec/notes.txt
  67 for details.)
  68
  69
  70 Requirements
  71 ============
  72
  73 To run the code, Python 2.1 or later must already be installed.  The
  74 latest release is recommended (2.1.3 or 2.2.1 as of this writing).
  75 Python is available from http://www.python.org/.
  76
  77
  78 Project Files & Directories
  79 ===========================
  80
  81 * README.txt: You're reading it.
  82
  83 * COPYING.txt: Copyright details for non-public-domain files (most are
  84   PD).
  85
  86 * HISTORY.txt: Release notes for the current and previous project
  87   releases.
  88
  89 * setup.py: Installation script.  See "Installation" below.
  90
  91 * install.py: Quick & dirty installation script.  Just run it.
  92
  93 * docutils: The project source directory, installed as a Python
  94   package.
  95
  96 * docs: The project user documentation directory.  Contains the
  97   following documents:
  98
  99   - docs/tools.txt: Docutils Front-End Tools
 100   - docs/rst/quickstart.txt: A ReStructuredText Primer
 101   - docs/rst/quickref.html: Quick reStructuredText (HTML only)
 102
 103 * spec: The project specification directory.  Contains PEPs (Python
 104   Enhancement Proposals), XML DTDs (document type definitions), and
 105   other documents.  The ``spec/rst`` directory contains the
 106   reStructuredText specification.  The ``spec/howto`` directory
 107   contains How-To documents for developers.
 108
 109 * tools: Directory for Docutils front-end tools.  See docs/tools.txt
 110   for documentation.
 111
 112 * test: Unit tests.  Not required to use the software, but very useful
 113   if you're planning to modify it.  See `Running the Test Suite`_
 114   below.
 115
 116
 117 Installation
 118 ============
 119
 120 The first step is to expand the ``.tar.gz`` or ``.tgz`` archive.  It
 121 contains a distutils setup file "setup.py".  OS-specific installation
 122 instructions follow.
 123
 124
 125 GNU/Linux, BSDs, Unix, MacOS X, etc.
 126 ------------------------------------
 127
 128 1. Open a shell.
 129
 130 2. Go to the directory created by expanding the archive::
 131
 132        cd <archive_directory_path>
 133
 134 3. Install the package::
 135
 136        python setup.py install
 137
 138    If the python executable isn't on your path, you'll have to specify
 139    the complete path, such as /usr/local/bin/python.  You may need
 140    root permissions to complete this step.
 141
 142 You can also just run install.py; it does the same thing.
 143
 144
 145 Windows
 146 -------
 147
 148 1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
 149    calling it these days).
 150
 151 2. Go to the directory created by expanding the archive::
 152
 153        cd <archive_directory_path>
 154
 155 3. Install the package::
 156
 157        <path_to_python.exe>\python setup.py install
 158
 159 If your system is set up to run Python when you double-click on .py
 160 files, you can run install.py to do the same as the above.
 161
 162
 163 MacOS 8/9
 164 ---------
 165
 166 1. Open the folder containing the expanded archive.
 167
 168 2. Double-click on the file "setup.py", which should be a "Python
 169    module" file.
 170
 171    If the file isn't a "Python module", the line endings are probably
 172    also wrong, and you will need to set up your system to recognize
 173    ".py" file extensions as Python files.  See
 174    http://gotools.sourceforge.net/mac/python.html for detailed
 175    instructions.  Once set up, it's easiest to start over by expanding
 176    the archive again.
 177
 178 3. The distutils options window will appear.  From the "Command" popup
 179    list choose "install", click "Add", then click "OK".
 180
 181 If install.py is a "Python module" (see step 2 above if it isn't), you
 182 can run it instead of the above.  The distutils options window will
 183 not appear.
 184
 185
 186 Usage
 187 =====
 188
 189 After unpacking and installing the Docutils package, the following
 190 shell commands will generate HTML for all included documentation::
 191
 192     cd <archive_directory_path>/tools
 193     buildhtml.py ../
 194
 195 The final directory name of the ``<archive_directory_path>`` is
 196 "docutils" for snapshots.  For official releases, the directory may be
 197 called "docutils-X.Y", where "X.Y" is the release version.
 198 Alternatively::
 199
 200     cd <archive_directory_path>
 201     tools/buildhtml.py --config=tools/docutils.conf
 202
 203 Some files may generate system messages (warnings and errors).  The
 204 ``tools/test.txt`` file contains 5 intentional errors.  (They test the
 205 error reporting mechanism!)
 206
 207 There are many front-end tools in the unpacked "tools" subdirectory.
 208 Most tools take up to two arguments, the source path and destination
 209 path, with STDIN and STDOUT being the defaults.  Use the "--help"
 210 option to the front-end tools for details on options and arguments.
 211 See `Docutils Front-End Tools`_ (``docs/tools.txt``) for full
 212 documentation.
 213
 214 The package modules are continually growing and evolving.  The
 215 ``docutils.statemachine`` module is usable independently.  It contains
 216 extensive inline documentation (in reStructuredText format of course).
 217
 218 Contributions are welcome!
 219
 220 .. _Docutils Front-End Tools: docs/tools.html
 221
 222
 223 Running the Test Suite
 224 ======================
 225
 226 To run the entire test suite, after installation_ open a shell and use
 227 the following commands::
 228
 229     cd <archive_directory_path>/test
 230     ./alltests.py
 231
 232 You should see a long line of periods, one for each test, and then a
 233 summary like this::
 234
 235     Ran 518 tests in 24.653s
 236
 237     OK
 238     Elapsed time: 26.189 seconds
 239
 240 The number of tests will grow over time, and the times reported will
 241 depend on the computer running the tests.  The difference between the
 242 two times represents the time required to set up the tests (import
 243 modules, create data structures, etc.).
 244
 245 If any of the tests fail, please `open a bug report`_ or `send
 246 email`_.  Please include all relevant output, information about your
 247 operating system, Python version, and Docutils version.  To see the
 248 Docutils version, use these commands::
 249
 250     cd ../tools
 251     ./quicktest.py --version
 252
 253 .. _open a bug report:
 254    http://sourceforge.net/tracker/?group_id=38414&atid=422030
 255 .. _send email: mailto:docutils-users@lists.sourceforge.net
 256    ?subject=Docutils%20test%20suite%20failure
 257
 258
 259 Getting Help
 260 ============
 261
 262 If you have questions or need assistance with Docutils or
 263 reStructuredText, please `post a message`_ to the `Docutils-Users
 264 mailing list`_.
 265
 266 .. _post a message: mailto:docutils-users@lists.sourceforge.net
 267 .. _Docutils-Users mailing list:
 268    http://lists.sourceforge.net/lists/listinfo/docutils-users
 269
 270 \f
 271 ..
 272    Local Variables:
 273    mode: indented-text
 274    indent-tabs-mode: nil
 275    sentence-end-double-space: t
 276    fill-column: 70
 277    End: