Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8489] trunk/docutils
|
From: <mi...@us...> - 2020-02-06 12:47:46
|
Revision: 8489
http://sourceforge.net/p/docutils/code/8489
Author: milde
Date: 2020-02-06 12:47:44 +0000 (Thu, 06 Feb 2020)
Log Message:
-----------
Documentation update.
Document the use of "setuptools" in "setup.py" and possible
alternatives.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/README.txt
trunk/docutils/docs/dev/distributing.txt
trunk/docutils/docs/dev/policies.txt
trunk/docutils/docs/dev/release.txt
trunk/docutils/docs/dev/repository.txt
trunk/docutils/setup.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/HISTORY.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -23,7 +23,7 @@
- Use importlib.import_module() to programmatically import modules.
- Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
- Installing with ``setup.py`` now requires ``setuptools``.
- Alternatively, install with `pip`_.
+ Alternatively, install with `pip`_ (or "manually").
* docutils/MANIFEST.in
Modified: trunk/docutils/README.txt
===================================================================
--- trunk/docutils/README.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/README.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -17,26 +17,18 @@
This is for those who want to get up & running quickly.
1. Docutils requires Python, available from
+ http://www.python.org/.
- 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:
+2. Install the latest release from PyPi with pip_::
- https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
+ python -m pip install docutils
- See `Releases & Snapshots`_ below for details.
+ To install a `development version`_, follow
+ the instructions in section `Installation`_ below.
-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.
+3. Use the front-end scripts to convert reStructuredText documents.
Try for example::
rst2html.py FAQ.txt FAQ.html (Unix)
@@ -44,7 +36,9 @@
See Usage_ below for details.
+.. _pip: https://pypi.org/project/pip/
+
Purpose
=======
@@ -75,37 +69,17 @@
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.7, and
-3.5 to 3.7 (cf. `Python 3 compatibility`_).
+Docutils is compatible with Python versions 2.7 and 3.5 to 3.7.
+Starting with Docutils 0.16, the code base supports both Python 2.7
+and 3.5+ natively. [#]_
+.. [#] Up to version 0.15, the Docutils codebase was translated "on-demand"
+ using the 2to3 tool.
+
Docutils uses the following packages for enhanced functionality,
if they are installed:
@@ -117,85 +91,69 @@
.. _Python: http://www.python.org/.
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
-.. _Pygments: http://pygments.org/
+.. _Pygments: https://pypi.org/project/Pygments/
+.. _setuptools: https://pypi.org/project/setuptools/
-Python 3 compatibility
-----------------------
+Development version
+===================
-Up to version 0.15, the Docutils codebase was translated "on-demand" using
-the 2to3 tool. Starting with Docutils 0.16, the code base supports both
-Python 2.7 and 3.5+ natively.
+While we are trying to follow a "release early & often" policy,
+features are added frequently. Since the code in the repository_
+is usually in a bug-free state, we recommend using a current snapshot
+or a working copy.
+To get a _`snapshot`, go to the code page and click the download snapshot
+button:
-Project Files & Directories
-===========================
+* Docutils code, documentation, front-end tools, and tests:
+ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
-* README.txt: You're reading it.
+* Sandbox (experimental, contributed code):
+ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
-* COPYING.txt: Public Domain Dedication and copyright details for
- non-public-domain files (most are PD).
+To keep up to date on the latest developments, download fresh copies of the
+snapshots regularly or use a `working copy of the Docutils code repository`__.
-* FAQ.txt: Frequently Asked Questions (with answers!).
+Continue with the `Installation`_ instructions below.
-* RELEASE-NOTES.txt: Summary of the major changes in recent releases.
+.. _repository: docs/dev/repository.html
+__ docs/dev/repository.html#checking-out-the-repository
-* HISTORY.txt: A detailed change log, for the current and all previous
- project releases.
+Installation
+============
-* BUGS.txt: Known bugs, and how to report a bug.
+Steps to install Docutils from source:
-* THANKS.txt: List of contributors.
+* Go to the directory containing the file ``setup.py``.
-* setup.py: Installation script. See "Installation" below.
+ A snapshot_ must be unpacked in a temporary directory (**not** directly in
+ Python's ``site-packages``) first.
-* install.py: Quick & dirty installation script. Just run it. For
- any kind of customization or help though, setup.py must be used.
+* Run ``setup.py install``. [#setup-requires-setuptools]_
+ On Windows systems it may be sufficient to double-click ``install.py``.
-* docutils: The project source directory, installed as a Python
- package.
+.. [#setup-requires-setuptools] ``setup.py`` requires the `setuptools`_
+ package. For a manual install see the options in `Setting up for Docutils
+ development`__.
+
+ __ docs/dev/policies.html#setting-up-for-docutils-development
+
+Optional steps:
-* docs: The project documentation directory. Read ``docs/index.txt``
- for an overview.
+* `running the test suite`_
-* docs/user: The project user documentation directory. Contains the
- following documents, among others:
+* `converting the documentation`_
- - 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)
+OS-specific installation instructions follow.
-* 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::
+2. Go to the directory containing ``setup.py``::
cd <archive_directory_path>
@@ -243,13 +201,7 @@
To install for different Python versions, repeat step 3 for every
required version.
-Optional steps:
-* `running the test suite`_
-
-* `converting the documentation`_
-
-
Usage
=====
@@ -268,6 +220,59 @@
Contributions are welcome!
+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.
+
+
Converting the documentation
============================
Modified: trunk/docutils/docs/dev/distributing.txt
===================================================================
--- trunk/docutils/docs/dev/distributing.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/docs/dev/distributing.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -65,10 +65,9 @@
The executable front-end tools are located in the ``tools/`` directory
of the Docutils tarball.
-The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
-end-users. You should install them to ``/usr/bin/``. You do not need
-to change the names (e.g. to ``docutils-rst2html.py``) because the
-``rst2`` prefix is unique.
+The ``rst2*.py`` tools are intended for end-users. You should install them
+to ``/usr/bin/``. You do not need to change the names (e.g. to
+``docutils-rst2html.py``) because the ``rst2`` prefix is unique.
Documentation
Modified: trunk/docutils/docs/dev/policies.txt
===================================================================
--- trunk/docutils/docs/dev/policies.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/docs/dev/policies.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -622,35 +622,58 @@
When making changes to the code, testing is a must. The code should
be run to verify that it produces the expected results, and the entire
test suite should be run too. The modified Docutils code has to be
-accessible to Python for the tests to have any meaning. There are two
+accessible to Python for the tests to have any meaning. There are several
ways to keep the Docutils code accessible during development:
1. Update your ``PYTHONPATH`` environment variable so that Python
- picks up your local working copy of the code. This is the
- recommended method.
+ picks up your local working copy of the code.
- We'll assume that the Docutils trunk is checked out under your
- ~/projects/ directory as follows::
+ We'll assume that the `Docutils trunk`__ is checked out under your
+ ``~/projects/`` directory.
- svn co https://<user>@docutils.svn.sourceforge.net/svnroot/docutils/trunk \
- docutils
-
For the bash shell, add this to your ``~/.profile``::
PYTHONPATH=$HOME/projects/docutils/docutils
- PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
+ PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils
export PYTHONPATH
The first line points to the directory containing the ``docutils``
package. The second line adds the directory containing the
third-party modules Docutils depends on. The third line exports
- this environment variable. You may also wish to add the ``tools``
- directory to your ``PATH``::
+ this environment variable.
+ You many also want to add the ``tools`` directory to your binary ``PATH``::
+
PATH=$PATH:$HOME/projects/docutils/docutils/tools
export PATH
-2. Before you run anything, every time you make a change, reinstall
+ __ repository.html
+
+2. Create a symlink to the docutils package directory somewhere in the
+ module serach path (``sys.path``), e.g., ::
+
+ ln -s ~/projects/docutils/docutils \
+ /usr/local/lib/python2.7/site-packages/
+
+ Alternatively, use a `path configuration file`__.
+
+ __ https://docs.python.org/library/site.html
+
+ You may also want to copy or link the front-end tools in
+ ``docutils/tools`` to a suitable place in your binary PATH, e.g., ::
+
+ ln -s ~/projects/docutils/docutils/tools/rst2html.py \
+ /usr/local/bin/rst2html
+
+3. Do an `editable install`__ with pip.
+
+ __ https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
+
+4. Install in `development mode`__ with setuptools.
+
+ __ https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode
+
+5. Before you run anything, every time you make a change, reinstall
Docutils::
python setup.py install
@@ -670,7 +693,7 @@
containing the following lines::
# source this file
- export PYTHONPATH=$PWD:$PWD/extras
+ export PYTHONPATH=$PWD:$PWD
export PATH=$PWD/tools:$PATH
Open a shell for this branch, ``cd`` to the ``docutils`` top-level
@@ -738,9 +761,8 @@
...
tools/ # For front ends etc.
...
- setup.py # Use Distutils to install the component
- # code and tools/ files into the right
- # places in Docutils.
+ setup.py # Install the component code and tools/ files
+ # into the right places.
userid/ # For *temporary* personal space.
Some sandbox projects are destined to move to the Docutils core once
Modified: trunk/docutils/docs/dev/release.txt
===================================================================
--- trunk/docutils/docs/dev/release.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/docs/dev/release.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -126,7 +126,7 @@
or via the [Download Snapshot] button at
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
- (c) Use Distutils to create the release tarball::
+ (c) Use `setuptools` to create the release tarball::
cd docutils
python setup.py sdist
Modified: trunk/docutils/docs/dev/repository.txt
===================================================================
--- trunk/docutils/docs/dev/repository.txt 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/docs/dev/repository.txt 2020-02-06 12:47:44 UTC (rev 8489)
@@ -107,6 +107,14 @@
svn update
+Switching the Repository Root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you changed your mind and want to use a different repository root,
+``cd`` into your working copy and type::
+
+ svn switch --relocate OLDROOT NEWROOT
+
Creating a local git clone
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -118,14 +126,7 @@
.. _git documentation: http://git-scm.com/documentation
-Switching the Repository Root
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you changed your mind and want to use a different repository root,
-``cd`` into your working copy and type::
-
- svn switch --relocate OLDROOT NEWROOT
-
.. _developer access:
Information for Developers
Modified: trunk/docutils/setup.py
===================================================================
--- trunk/docutils/setup.py 2020-02-06 12:47:34 UTC (rev 8488)
+++ trunk/docutils/setup.py 2020-02-06 12:47:44 UTC (rev 8489)
@@ -12,9 +12,13 @@
from setuptools import setup
except ImportError:
print('Error: The "setuptools" module, which is required for the')
- print('installation of Docutils, could not be found. You may need to ')
- print('install a package called "python-setuptools" (or similar) on your ')
- print('system using your package manager.')
+ print(' installation of Docutils, could not be found.\n')
+ print(' You may install it with `python -m pip install setuptools`')
+ print(' or from a package called "python-setuptools" (or similar)')
+ print(' using your system\'s package manager.\n')
+ print(' Alternatively, install a release from PyPi with')
+ print(' `python -m pip install docutils`.')
+
sys.exit(1)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
