diff options
Diffstat (limited to 'docutils/README.txt')
-rw-r--r-- | docutils/README.txt | 334 |
1 files changed, 0 insertions, 334 deletions
diff --git a/docutils/README.txt b/docutils/README.txt deleted file mode 100644 index c2005ffaf..000000000 --- a/docutils/README.txt +++ /dev/null @@ -1,334 +0,0 @@ -================== - README: Docutils -================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Quick-Start -=========== - -This is for those who want to get up & running quickly. Read on for -complete details. - -1. Get and install the latest release of Python, available from - - http://www.python.org/ - - Python 2.2 or later [1]_ is required; Python 2.2.2 or later is - recommended. - -2. Use the latest Docutils code. Get the code from Subversion or from - the snapshot: - - http://docutils.sf.net/docutils-snapshot.tgz - - See `Releases & Snapshots`_ below for details. - -3. Unpack the tarball in a temporary directory (**not** directly in - Python's ``site-packages``) and run ``install.py`` with admin - rights. On Windows systems it may be sufficient to double-click - ``install.py``. On Unix or Mac OS X, type:: - - su - (enter admin password) - ./install.py - - See Installation_ below for details. - -4. Use a front-end tool from the "tools" subdirectory of the same - directory as in step 3. For example:: - - cd tools - ./rst2html.py ../FAQ.txt ../FAQ.html (Unix) - python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows) - - See Usage_ below for details. - - -Purpose -======= - -The purpose of the Docutils project is to create a set of tools for -processing plaintext documentation into useful formats, such as HTML, -XML, and LaTeX. Support for the following sources has been -implemented: - -* Standalone files. - -* `PEPs (Python Enhancement Proposals)`_. - -Support for the following sources is planned: - -* Inline documentation from Python modules and packages, extracted - with namespace context. - -* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts). - -* Wikis, with global reference lookups of "wiki links". - -* Compound documents, such as multiple chapter files merged into a - book. - -* And others as discovered. - -.. _PEPs (Python Enhancement Proposals): - http://www.python.org/peps/pep-0012.html - - -Releases & Snapshots -==================== - -While we are trying to follow a "release early & often" policy, -features are added very frequently. Since the code in the Subversion -repository is usually in a bug-free state, we recommend that you use -the current snapshot (which is usually updated within an hour of -changes being committed to the repository): - -* Snapshot of Docutils code, documentation, front-end tools, and - tests: http://docutils.sf.net/docutils-snapshot.tgz - -* Snapshot of the Sandbox (experimental, contributed code): - http://docutils.sf.net/docutils-sandbox-snapshot.tgz - -To keep up to date on the latest developments, download fresh copies -of the snapshots regularly. New functionality is being added weekly, -sometimes daily. (There's also the `Subversion repository`_.) - -.. _Subversion repository: docs/dev/repository.html - - -Requirements -============ - -To run the code, Python 2.2 or later [1]_ must already be installed. -The latest release is recommended. Python is available from -http://www.python.org/. - -The `Python Imaging Library`, or PIL, is used for some image -manipulation operations if it is installed. - -.. [1] Python 2.1 may be used providing the compiler package is - installed. The compiler package can be found in the Tools/ - directory of Python 2.1's source distribution. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ -.. _Optik: http://optik.sourceforge.net/ - - -Project Files & Directories -=========================== - -* README.txt: You're reading it. - -* COPYING.txt: Public Domain Dedication and copyright details for - non-public-domain files (most are PD). - -* FAQ.txt: Frequently Asked Questions (with answers!). - -* RELEASE-NOTES.txt: Summary of the major changes in recent releases. - -* HISTORY.txt: A detailed change log, for the current and all previous - project releases. - -* BUGS.txt: Known bugs, and how to report a bug. - -* THANKS.txt: List of contributors. - -* setup.py: Installation script. See "Installation" below. - -* install.py: Quick & dirty installation script. Just run it. For - any kind of customization or help though, setup.py must be used. - -* docutils: The project source directory, installed as a Python - package. - -* extras: Directory for third-party modules that Docutils depends on. - These are only installed if they're not already present. - -* docs: The project documentation directory. Read ``docs/index.txt`` - for an overview. - -* docs/user: The project user documentation directory. Contains the - following documents, among others: - - - docs/user/tools.txt: Docutils Front-End Tools - - docs/user/latex.txt: Docutils LaTeX Writer - - docs/user/rst/quickstart.txt: A ReStructuredText Primer - - docs/user/rst/quickref.html: Quick reStructuredText (HTML only) - -* docs/ref: The project reference directory. - ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText - reference. - -* licenses: Directory containing copies of license files for - non-public-domain files. - -* tools: Directory for Docutils front-end tools. See - ``docs/user/tools.txt`` for documentation. - -* test: Unit tests. Not required to use the software, but very useful - if you're planning to modify it. See `Running the Test Suite`_ - below. - - -Installation -============ - -The first step is to expand the ``.tgz`` archive in a temporary -directory (**not** directly in Python's ``site-packages``). It -contains a distutils setup file "setup.py". OS-specific installation -instructions follow. - - -GNU/Linux, BSDs, Unix, Mac OS X, etc. -------------------------------------- - -1. Open a shell. - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - python setup.py install - - If the python executable isn't on your path, you'll have to specify - the complete path, such as /usr/local/bin/python. You may need - root permissions to complete this step. - - You can also just run install.py; it does the same thing. - - -Windows -------- - -Just double-click ``install.py``. If this doesn't work, try the -following: - -1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're - calling it these days). - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - <path_to_python.exe>\python setup.py install - - -Usage -===== - -After unpacking and installing the Docutils package, the following -shell commands will generate HTML for all included documentation:: - - cd <archive_directory_path>/tools - ./buildhtml.py ../ - -On Windows systems, type:: - - cd <archive_directory_path>\tools - python buildhtml.py .. - -The final directory name of the ``<archive_directory_path>`` is -"docutils" for snapshots. For official releases, the directory may be -called "docutils-X.Y.Z", where "X.Y.Z" is the release version. -Alternatively:: - - cd <archive_directory_path> - tools/buildhtml.py --config=tools/docutils.conf (Unix) - python tools\buildhtml.py --config=tools\docutils.conf (Windows) - -Some files may generate system messages (warnings and errors). The -``docs/user/rst/demo.txt`` file (under the archive directory) contains -5 intentional errors. (They test the error reporting mechanism!) - -There are many front-end tools in the unpacked "tools" subdirectory. -You may want to begin with the "rst2html.py" front-end tool. Most -tools take up to two arguments, the source path and destination path, -with STDIN and STDOUT being the defaults. Use the "--help" option to -the front-end tools for details on options and arguments. See -Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation. - -The package modules are continually growing and evolving. The -``docutils.statemachine`` module is usable independently. It contains -extensive inline documentation (in reStructuredText format of course). - -Contributions are welcome! - - -Running the Test Suite -====================== - -To run the entire test suite, after installation_ open a shell and use -the following commands:: - - cd <archive_directory_path>/test - ./alltests.py - -Under Windows, type:: - - cd <archive_directory_path>\test - python alltests.py - -You should see a long line of periods, one for each test, and then a -summary like this:: - - Ran 518 tests in 24.653s - - OK - Elapsed time: 26.189 seconds - -The number of tests will grow over time, and the times reported will -depend on the computer running the tests. The difference between the -two times represents the time required to set up the tests (import -modules, create data structures, etc.). - -If any of the tests fail, please `open a bug report`_, `send email`_, -or post a message via the `web interface`_. Please include all -relevant output, information about your operating system, Python -version, and Docutils version. To see the Docutils version, use these -commands in the shell:: - - cd ../tools - ./quicktest.py --version - -Windows users type these commands:: - - cd ..\tools - python quicktest.py --version - -.. _open a bug report: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 -.. _send email: mailto:docutils-users@lists.sourceforge.net - ?subject=Test%20suite%20failure -.. _web interface: http://post.gmane.org/post.php - ?group=gmane.text.docutils.user&subject=Test+suite+failure - - -Getting Help -============ - -If you have questions or need assistance with Docutils or -reStructuredText, please post a message to the Docutils-users_ mailing -list. - -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |