docutils-0.15.2.tar.gz

========================= README: Docutils 0.15.2 ========================= :Author: David Goodger :Contact: goodger@python.org :Date: $Date: 2019-07-30 11:51:07 +0200 (Di, 30. Jul 2019) $ :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. 1. Docutils requires Python (version 2.6 or later), available from http://www.python.org/ See Requirements_ below for details. 2. Use the latest Docutils code. Get the code from the `Subversion repository`_ or from the snapshot: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ See `Releases & Snapshots`_ below for details. 3. Unpack the tarball in a temporary directory (**not** directly in Python's ``site-packages``), go to the directory created by expanding the archive, and run ``setup.py install``. On Windows systems it may be sufficient to double-click ``install.py``. See Installation_ below for details. 4. Use the front-end scripts to convert reStructuredText documents. Try for example:: rst2html.py FAQ.txt FAQ.html (Unix) python tools/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 frequently. Since the code in the Subversion repository is usually in a bug-free state, we recommend that you use a current snapshot. To get a snapshot, go to the code page and click the download snapshot button: * Docutils code, documentation, front-end tools, and tests: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ * Sandbox (experimental, contributed code): https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/ To keep up to date on the latest developments, download fresh copies of the snapshots regularly or use a working copy of the `Subversion repository`_. .. _Subversion repository: docs/dev/repository.html Requirements ============ To run the code, Python_ must be installed. Docutils is compatible with Python versions 2.6, 2.7, and versions 3.3 to 3.5 (cf. `Python 3 compatibility`_). Docutils uses the following packages for enhanced functionality, if they are installed: * The `Python Imaging Library`_, or PIL, is used for some image manipulation operations. * The `Pygments`_ syntax highlighter is used for content of `code` directives and roles. .. _Python: http://www.python.org/. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ .. _Pygments: http://pygments.org/ Python 3 compatibility ---------------------- The Docutils codebase is written for Python 2 and uses "on-demand" translation for `porting to Python 3`_. * The `setup.py` script generates Python 3 compatible sources in ``build/`` and tests in ``tests3/`` sub-directories during installation_ with Python 3. * The scripts in the ``tools/`` sub-directory work with all supported Python versions without conversion. * To convert the sources without installing (e.g. for testing), run ``python3 setup.py build``. * When editing the source, do changes on the Python 2 versions of the files and re-run the build command. .. _porting to Python 3: http://docs.python.org/py3k/howto/pyporting.html 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. * 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. Generated directories when installing under Python 3: * build: Converted sources. * test3: Converted tests. 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 (you may need root permissions to complete this step):: su (enter admin password) 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``. To install for a specific Python version, use this version in the setup call, e.g. :: python3.1 setup.py install To install for different Python versions, repeat step 3 for every required version. The last installed version will be used in the `shebang line`_ of the ``rst2*.py`` wrapper scripts. .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29 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 To install for a specific python version, specify the Python executable for this version. To install for different Python versions, repeat step 3 for every required version. Optional steps: * `running the test suite`_ * `converting the documentation`_ Usage ===== There are many front-end tools in the unpacked "tools" subdirectory. Installation under Unix places copies in the PATH. 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 t