1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
===============================
Docutils_ Distributor's Guide
===============================
:Author: Lea Wiemann
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 7889 $
:Date: $Date: 2015-05-08 17:56:32 +0200 (Fr, 08 Mai 2015) $
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
.. contents::
This document describes how to create packages of Docutils (e.g. for
shipping with a Linux distribution). If you have any questions,
please direct them to the Docutils-develop_ mailing list.
First, please download the most current `release tarball`_ and unpack
it.
.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
.. _release tarball: http://docutils.sourceforge.net/#download
Dependencies
============
Docutils has the following dependencies:
* Python 2.4 or later is required. Use ">= Python 2.4" in the
dependencies.
* Docutils may optionally make use of the PIL (`Python Imaging
Library`_). If PIL is present, it is automatically detected by
Docutils.
* Docutils recommends the `Pygments`_ syntax hightlighter. If available, it
is used for highlighting the content of `code directives`_ and roles as
well as included source code files (with the "code" option to the include_
directive).
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
.. _Pygments: http://pygments.org/
.. _code directives: ../ref/rst/directives.html#code
.. _include: ../ref/rst/directives.html#include
Python Files
============
The Docutils Python files must be installed into the
``site-packages/`` directory of Python. Running ``python setup.py
install`` should do the trick, but if you want to place the files
yourself, you can just install the ``docutils/`` directory of the
Docutils tarball to ``/usr/lib/python/site-packages/docutils/``. In
this case you should also compile the Python files to ``.pyc`` and/or
``.pyo`` files so that Docutils doesn't need to be recompiled every
time it's executed.
Executables
===========
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.
Documentation
=============
The documentation should be generated using ``buildhtml.py``. To
generate HTML for all documentation files, go to the ``tools/``
directory and run::
# Place html4css1.css in base directory.
cp ../docutils/writers/html4css1/html4css1.css ..
./buildhtml.py --stylesheet-path=../html4css1.css ..
Then install the following files to ``/usr/share/doc/docutils/`` (or
wherever you install documentation):
* All ``.html`` and ``.txt`` files in the base directory.
* The ``docs/`` directory.
Do not install the contents of the ``docs/`` directory directly to
``/usr/share/doc/docutils/``; it's incomplete and would contain
invalid references!
* The ``licenses/`` directory.
* ``html4css1.css`` in the base directory.
Removing the ``.txt`` Files
---------------------------
If you are tight with disk space, you can remove all ``.txt`` files in
the tree except for:
* those in the ``licenses/`` directory because they have not been
processed to HTML and
* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
be readable in source form.
Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
with the ``--no-source-link`` switch to avoid broken references to the
source files.
Other Files
===========
You may want to install the Emacs-Lisp files
``tools/editors/emacs/*.el`` into the appropriate directory.
Configuration File
==================
It is possible to have a system-wide configuration file at
``/etc/docutils.conf``. However, this is usually not necessary. You
should *not* install ``tools/docutils.conf`` into ``/etc/``.
Tests
=====
While you probably do not need to ship the tests with your
distribution, you can test your package by installing it and then
running ``alltests.py`` from the ``tests/`` directory of the Docutils
tarball.
For more information on testing, view the `Docutils Testing`_ page.
.. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html
|
