docutils/docs/dev/distributing.txt

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