Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9290] trunk/docutils
|
From: <mi...@us...> - 2022-12-01 21:13:00
|
Revision: 9290
http://sourceforge.net/p/docutils/code/9290
Author: milde
Date: 2022-12-01 21:12:57 +0000 (Thu, 01 Dec 2022)
Log Message:
-----------
Update documentation.
Simplify/update instructions for installing,
Simplify/update instructions for building docs
(there is now an up-to-date docutils.conf in the "docutils root" archive path.
Update links.
Modified Paths:
--------------
trunk/docutils/README.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/dev/repository.txt
trunk/docutils/docs/index.txt
Modified: trunk/docutils/README.txt
===================================================================
--- trunk/docutils/README.txt 2022-12-01 16:11:22 UTC (rev 9289)
+++ trunk/docutils/README.txt 2022-12-01 21:12:57 UTC (rev 9290)
@@ -24,7 +24,7 @@
2. Install the latest stable release from PyPi with pip_::
- python3 -m pip install docutils
+ pip install docutils
For alternatives and details, see section `Installation`_ below.
@@ -31,8 +31,7 @@
3. Use the `front-end scripts`_ to convert reStructuredText documents.
Try for example::
- rst2html.py FAQ.txt FAQ.html (Unix)
- docutils FAQ.txt FAQ.html (Unix and Windows)
+ docutils FAQ.txt FAQ.html
See Usage_ below for details.
@@ -40,7 +39,7 @@
Purpose
=======
-The purpose of the Docutils project is to create a set of tools for
+The purpose of the Docutils project is to provide a set of tools for
processing plaintext documentation into useful formats, such as HTML,
LaTeX, troff (man pages), OpenOffice, and native XML. Support for the
following sources has been implemented:
@@ -75,29 +74,28 @@
To run the code, Python_ must be installed.
(Python is pre-installed with most Linux distributions.)
-* Docutils 0.19.1b.dev requires Python 3.7 or later.
-* Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.
-* Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.
+* Since version 0.19, Docutils requires Python 3.7 or later.
+* Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.
.. _Python: https://www.python.org/.
-Optional Dependencies
----------------------
+Recommendations
+---------------
Docutils uses the following packages for enhanced functionality, if they
are installed:
-* Installation_ is usually done with pip_ or setuptools_.
+* The recommended installer is pip_, setuptools_ works, too.
-* The `Python Imaging Library`_, or PIL, is used for some image
+* The `Python Imaging Library`_ (PIL) is used for some image
manipulation operations.
* The `Pygments`_ package provides syntax highlight of "code" directives
and roles.
-* The `myst`_ or `recommonmark`_ parsers can be used to parse input in
- Markdown format.
+* The `myst`_, `pycmark`_, or `recommonmark`_ parsers can be used to
+ parse input in "Markdown" (CommonMark_) format.
The `Docutils Link List <docs/user/links.html>`__ records projects that
users of Docutils and reStructuredText may find useful.
@@ -107,141 +105,124 @@
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
.. _Pygments: https://pypi.org/project/Pygments/
.. _myst: https://pypi.org/project/myst-docutils/
+.. _pycmark: https://pypi.org/project/pycmark/
.. _recommonmark: https://github.com/rtfd/recommonmark
+.. _CommonMark: https://spec.commonmark.org/0.30/
-Development version
-===================
+Installation
+============
-While we are trying to follow a "release early & often" policy,
-features are added frequently.
-Since the code in the `Docutils version repository`_ is usually in a
-bug-free state, we recommend using a current snapshot or a working copy.
+The `Python Packaging User Guide`_ gives details how to
+`use pip for installing`_.
-Snapshots:
- To get a repository _`snapshot`, go to
- https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
- and click the download snapshot button.
+* The simplest way is to install the latest *stable release* from PyPi::
-Repository check-out:
- To keep up to date on the latest developments,
- use a `working copy`__ of the `Docutils version repository`_.
+ pip install docutils
-Continue with the `Installation`_ instructions below.
+* To install a *pre-relase*, append the option ``--pre``.
-.. _Docutils version repository: docs/dev/repository.html
-.. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
+* To install a `development version`_ *from source*:
-__ docs/dev/repository.html#checking-out-the-repository
+ 1. Open a shell
+ 2. Go to the directory containing the file ``setup.py``.
-Installation
-============
+ 3. Install the package with **one** of the following commands::
-* The simplest way is to install the latest stable release from PyPi with
- pip_::
+ pip install -e . # editable install
+ pip install . # regular install
+ python setup.py # regular install with setuptools
- python3 -m pip install docutils
+ 4. Optional steps:
- To install a pre-relase, append the option ``--pre``.
+ * `Running the test suite`_
+ * `Converting the documentation`_
-* To install a `development version`_ from source with `setuptools`_:
+ See also the OS-specific installation instructions below and
+ the `Docutils version repository`_ documentation.
- * Go to the directory containing the file ``setup.py``.
+* To install for a *specific Python version*, use this version in the
+ setup call, e.g. ::
- A snapshot_ must be unpacked in a temporary directory
- (**not** directly in Python's ``site-packages``) first.
+ python3.11 -m pip install docutils
- * Run ``setup.py install``.
- See also OS-specific installation instructions below.
+ If the python executable isn't on your path, you'll have to specify the
+ complete path, such as ``/usr/local/bin/python3.11``.
- Optional steps:
-
- * `Running the test suite`_
-
- * `Converting the documentation`_
+ To install for different Python versions, repeat step 3 for every
+ required version. The last installed version will be used for the
+ ``docutils`` command line application.
-* For installing "by hand" or in "development mode", see the
- `editable installs`_ section in the `Docutils version repository`_
- documentation.
+.. _Python Packaging User Guide: https://packaging.python.org/en/latest/
+.. _use pip for installing:
+ https://packaging.python.org/en/latest/tutorials/installing-packages/
+ #use-pip-for-installing
+.. _"editable" install:
+ https://pip.pypa.io/en/stable/topics/local-project-installs/
+ #editable-installs
- .. _editable installs: docs/dev/repository.html#editable-installs
-
GNU/Linux, BSDs, Unix, Mac OS X, etc.
-------------------------------------
-1. Open a shell.
+* Use ``su`` or ``sudo`` for a system-wide
+ installation as ``root``, e.g.::
-2. Go to the directory containing ``setup.py``::
+ sudo pip install docutils
- cd <archive_directory_path>
-3. Install the package (you may need root permissions to complete this
- step)::
+Windows
+-------
- su
- (enter admin password)
- python3 setup.py install
+* The Python FAQ explains `how to run a Python program under Windows`__.
- If the python executable isn't on your path, you'll have to specify
- the complete path, such as ``/usr/local/bin/python``.
+ __ https://docs.python.org/3/faq/windows.html
+ #how-do-i-run-a-python-program-under-windows
- To install for a specific Python version, use this version in the
- setup call, e.g. ::
+* Usually, pip_ is automatically installed if you are using Python
+ downloaded from https://python.org. If not, see the
+ `pip documentation <https://pip.pypa.io/en/stable/installation/>`__.
- python3.7 setup.py install
+* The command window should recognise the word ``py`` as an instruction to
+ start the interpreter, e.g.
- 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 `front-end scripts`_.
+ py -m pip install docutils
- .. _shebang line: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
+ If this does not work, you may have to specify the full path to the
+ Python executable.
-Windows
--------
-Just double-click ``install.py``. If this doesn't work, try the
-following:
+Usage
+=====
-1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
- calling it these days).
+Start the "docutils" command line application with::
-2. Go to the directory created by expanding the archive::
+ docutils [options] [<source> [<destination>]]
- cd <archive_directory_path>
+The default action is to convert a reStructuredText_ document to HTML5,
+for example::
-3. Install the package::
+ docutils test.rst test.html
- <path_to_python.exe>\python setup.py install
+Read the ``--help`` option output for details on options and arguments and
+`Docutils Front-End Tools`_ for the full documentation of the various tools.
- To install for a specific python version, specify the Python
- executable for this version.
+For programmatic use of the `docutils` Python package, read the
+`API Reference Material`_ and the source code.
+Remaining questions may be answered in the `Docutils Project
+Documentation`_ or the Docutils-users_ mailing list.
- To install for different Python versions, repeat step 3 for every
- required version.
-
-
-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 the ``--help`` option to
-the front-end tools for details on options and arguments. See
-`Docutils Front-End Tools`_ 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!
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _front-end scripts:
.. _Docutils Front-End Tools: docs/user/tools.html
+.. _API Reference Material: /docs/index.html
+ #api-reference-material-for-client-developers
+.. _Docutils Project Documentation: /docs/index.html
+
Project Files & Directories
===========================
@@ -295,6 +276,32 @@
below.
+Development version
+===================
+
+While we are trying to follow a "release early & often" policy,
+features are added frequently.
+We recommend using a current snapshot or a working copy of the repository.
+
+Repository check-out:
+ To keep up to date on the latest developments,
+ use a `working copy`__ of the `Docutils version repository`_.
+
+Snapshots:
+ To get a repository _`snapshot`, go to
+ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
+ and click the download snapshot button.
+
+ Unpack in a temporary directory,
+ **not** directly in Python's ``site-packages``.
+
+Continue with the `Installation`_ instructions below.
+
+__ docs/dev/repository.html#checking-out-the-repository
+.. _Docutils version repository: docs/dev/repository.html
+.. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
+
+
Converting the documentation
============================
@@ -301,23 +308,18 @@
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 ../
+ cd <archive_directory_path>
+ tools/buildhtml.py .
On Windows systems, type::
- cd <archive_directory_path>\tools
- python buildhtml.py ..
+ cd <archive_directory_path>
+ py tools\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
five intentional errors. (They test the error reporting mechanism!)
@@ -343,15 +345,17 @@
You should see a long line of periods, one for each test, and then a
summary like this::
- Ran 1111 tests in 24.653s
+ Ran 1744 tests in 5.859s
- OK
- Elapsed time: 26.189 seconds
+ OK (skipped=1)
+ Elapsed time: 6.235 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.).
+depend on the computer running the tests.
+Some test are skipped, if optional dependencies (`recommendations`_)
+are missing.
+The difference between the two times represents the time required to set
+up the tests (import modules, create data structures, etc.).
A copy of the test output is written to the file ``alltests.out``.
@@ -359,8 +363,7 @@
(see `Bugs <BUGS.html>`_).
Please include all relevant output, information about your operating
system, Python version, and Docutils version. To see the Docutils
-version, look at the test output or use one of the `front-end scripts`_
-with the ``--version`` option, e.g.::
+version, look at the test output or use ::
docutils --version
@@ -376,7 +379,7 @@
============
All documentation can be reached from the `Project Documentation
-Overview`_.
+Overview`_.
The SourceForge `project page`_ has links to the tracker, mailing
lists, and code repository.
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2022-12-01 16:11:22 UTC (rev 9289)
+++ trunk/docutils/RELEASE-NOTES.txt 2022-12-01 21:12:57 UTC (rev 9290)
@@ -29,8 +29,8 @@
.. code:: diff
- - rst2latex.py --use-latex-abstract xmpl.txt > xmpl.tex
- + docutils --writer=latex --use-latex-abstract xmpl.txt > xmpl.tex
+ - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex
+ + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex
Exceptions:
The auxilliary script ``rst2odt_prepstyles.py`` will become
Modified: trunk/docutils/docs/dev/repository.txt
===================================================================
--- trunk/docutils/docs/dev/repository.txt 2022-12-01 16:11:22 UTC (rev 9289)
+++ trunk/docutils/docs/dev/repository.txt 2022-12-01 21:12:57 UTC (rev 9290)
@@ -137,6 +137,7 @@
There are several ways to ensure that edits to the Docutils code are
picked up by Python.
+
We'll assume that the Docutils "trunk" is checked out under the
``~/projects/`` directory.
@@ -144,79 +145,73 @@
python3 -m pip install -e ~/projects/docutils/docutils
- __ https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+ __ https://pip.pypa.io/en/stable/topics/local-project-installs/
+ #editable-installs
-2. Install in `development mode`__ with setuptools_.
+2. Install "manually".
- __ https://setuptools.pypa.io/en/latest/userguide/development_mode.html
- #development-mode
+ Ensure that the "docutils" package is in the module search path
+ (``sys.path``) by one of the following actions:
- .. _install manually:
+ a) Set the ``PYTHONPATH`` environment variable.
-3. Install "manually".
+ For the bash shell, add this to your ``~/.profile``::
- Ensure that the "docutils" package is in ``sys.path`` by
- one of the following actions:
-
- * Set the ``PYTHONPATH`` environment variable so that Python
- picks up your local working copy of the code.
-
- For the bash shell, add this to your ``~/.profile``::
-
PYTHONPATH=$HOME/projects/docutils/docutils
export PYTHONPATH
- The first line points to the directory containing the ``docutils``
- package. The second line exports the environment variable.
+ The first line points to the directory containing the ``docutils``
+ package, the second line exports the environment variable.
- * Create a symlink to the docutils package directory somewhere in the
- module search path (``sys.path``), e.g., ::
+ b) Create a symlink to the docutils package directory somewhere in the
+ ``sys.path``, e.g., ::
ln -s ~/projects/docutils/docutils \
/usr/local/lib/python3.9/dist-packages/
- * Use a `path configuration file`__.
+ c) Use a `path configuration file`__.
- __ https://docs.python.org/library/site.html
+ __ https://docs.python.org/library/site.html
- Optionally, add some or all `front-end tools`_
- to the binary search path, e.g.,
- add the ``tools`` directory to the ``PATH`` variable::
+ Optionally, add some or all `front-end tools`_ to the binary search
+ path, e.g.:
+ a) add the ``tools`` directory to the ``PATH`` variable::
+
PATH=$PATH:$HOME/projects/docutils/docutils/tools
export PATH
- or link idividual front-end tools to a suitable place
- in the binary path::
+ or
+ b) link idividual front-end tools to a suitable place in the binary
+ path::
+
ln -s ~/projects/docutils/docutils/tools/docutils-cli.py \
/usr/local/bin/docutils
-5. Reinstall Docutils after any change::
+3. Do a regular install. Repeat after any change. ::
- python3 setup.py install
+ ./setup.py install
.. CAUTION::
- This method is **not** recommended for day-to-day development;
- it's too easy to forget. Confusion inevitably ensues.
+ This method is **not** recommended for day-to-day development!
- If you install Docutils this way, Python will always pick up the
- last-installed copy of the code. If you ever forget to
- reinstall the "docutils" package, Python won't see your latest
- changes.
+ If you ever forget to reinstall the "docutils" package, Python
+ won't see your latest changes. Confusion inevitably ensues.
-A useful addition to the ``docutils`` top-level directory in branches
-and alternate copies of the code is a ``set-PATHS`` file
-containing the following lines::
+Tip:
+ A useful addition to the ``docutils`` top-level directory in
+ *SVN branches* and *alternate copies* of the code is a ``set-PATHS``
+ shell script containing the following lines::
- # source this file
- export PYTHONPATH=$PWD:$PWD
- export PATH=$PWD/tools:$PATH
+ # source this file
+ export PYTHONPATH=$PWD:$PWD
+ export PATH=$PWD/tools:$PATH
-Open a shell for this branch, ``cd`` to the ``docutils`` top-level
-directory, and "source" this file. For example, using the bash
-shell::
+ Open a shell for this branch, ``cd`` to the ``docutils`` top-level
+ directory, and "source" this file. For example, using the bash
+ shell::
$ cd some-branch/docutils
$ . set-PATHS
Modified: trunk/docutils/docs/index.txt
===================================================================
--- trunk/docutils/docs/index.txt 2022-12-01 16:11:22 UTC (rev 9289)
+++ trunk/docutils/docs/index.txt 2022-12-01 21:12:57 UTC (rev 9290)
@@ -201,6 +201,7 @@
:Security: `Deploying Docutils Securely <howto/security.html>`__
* `Inside A Docutils Command-Line Front-End Tool <howto/cmdline-tool.html>`__
+* `Runtime Settings Processing <dev/runtime-settings-processing.html>`__
* `Writing HTML (CSS) Stylesheets for Docutils
<howto/html-stylesheets.html>`__
* `Docutils Internationalization <howto/i18n.html>`__
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
