/ README.rst
README.rst
1 ============================ 2 README: Docutils 0.23b.dev 3 ============================ 4 5 :Author: David Goodger 6 :Contact: goodger@python.org 7 :Date: $Date: 2025-07-29 18:11:43 +0200 (Di, 29. Jul 2025) $ 8 :Web site: https://docutils.sourceforge.io/ 9 :Copyright: This document has been placed in the public domain. 10 11 :Abstract: Docutils is a modular system for processing documentation into 12 useful formats, such as HTML, XML, and LaTeX. 13 For input Docutils supports reStructuredText, an easy-to-read, 14 what-you-see-is-what-you-get plaintext markup syntax. 15 16 .. contents:: 17 18 19 Quick-Start 20 =========== 21 22 This is for those who want to get up & running quickly. 23 24 1. Docutils requires **Python**, available from 25 https://www.python.org/. 26 See Dependencies_ below for details. 27 28 2. Install the latest stable release from PyPi with pip_:: 29 30 pip install docutils 31 32 For alternatives and details, see section `Installation`_ below. 33 34 3. Use the `front-end scripts`_ to convert reStructuredText documents. 35 Try for example:: 36 37 docutils FAQ.rst FAQ.html 38 39 See Usage_ below for details. 40 41 42 Purpose 43 ======= 44 45 The purpose of the Docutils project is to provide a set of tools for 46 processing plaintext documentation into useful formats, such as HTML, 47 LaTeX, troff (man pages), OpenOffice, and native XML. Support for the 48 following sources has been implemented: 49 50 * Standalone files. 51 52 * `PEPs (Python Enhancement Proposals)`_. 53 54 Support for the following sources is planned or provided by 55 `third party tools`_: 56 57 * Inline documentation from Python modules and packages, extracted 58 with namespace context. 59 60 * Email (RFC-822 headers, quoted excerpts, signatures, MIME parts). 61 62 * Wikis, with global reference lookups of "wiki links". 63 64 * Compound documents, such as multiple chapter files merged into a 65 book. 66 67 * And others as discovered. 68 69 .. _PEPs (Python Enhancement Proposals): 70 https://peps.python.org/pep-0012 71 .. _third party tools: docs/user/links.html#related-applications 72 73 74 Dependencies 75 ============ 76 77 To run the code, Python_ must be installed. 78 (Python is pre-installed with most Linux distributions.) 79 80 * Since version 0.21, Docutils requires Python 3.9 or later. 81 * Docutils versions 0.19 to 0.20.1 require Python 3.7 or later. 82 * Docutils versions 0.16 to 0.18 require Python 2.7 or 3.5+. 83 84 The **type hints** added in version 0.22 use Python 3.10 syntax. 85 However, the Python interpreter treats them as annotations 86 unless ``typing.TYPE_CHECKING`` is set to ``True``. 87 88 .. _Python: https://www.python.org/. 89 90 91 Recommendations 92 --------------- 93 94 Docutils uses the following packages for enhanced functionality, if they 95 are installed: 96 97 * The recommended installer is pip_, setuptools_ works, too. 98 99 * The `Python Imaging Library`_ (PIL) is used for some image 100 manipulation operations. 101 102 * The `Pygments`_ package provides syntax highlight of "code" directives 103 and roles. 104 105 * The `myst`_, `pycmark`_, or `recommonmark`_ parsers can be used to 106 parse input in "Markdown" (CommonMark_) format. 107 108 The `Docutils Link List <docs/user/links.html>`__ records projects that 109 users of Docutils and reStructuredText may find useful. 110 111 .. _pip: https://pypi.org/project/pip/ 112 .. _setuptools: https://pypi.org/project/setuptools/ 113 .. _Python Imaging Library: http://www.pythonware.com/products/pil/ 114 .. _Pygments: https://pypi.org/project/Pygments/ 115 .. _myst: https://pypi.org/project/myst-docutils/ 116 .. _pycmark: https://pypi.org/project/pycmark/ 117 .. _recommonmark: https://github.com/rtfd/recommonmark 118 .. _CommonMark: https://spec.commonmark.org/0.30/ 119 120 121 Installation 122 ============ 123 124 The `Python Packaging User Guide`_ gives details how to 125 `use pip for installing`_. 126 127 * The simplest way is to install the latest *stable release* from PyPi:: 128 129 pip install docutils 130 131 * To install a *pre-relase*, append the option ``--pre``. 132 133 * To install a `development version`_ *from source*: 134 135 1. Open a shell 136 137 2. Go to the directory containing the ``pyproject.toml`` file. 138 139 3. Install the package with **one** of the following commands:: 140 141 pip install -e . # editable install 142 pip install . # regular install 143 144 or do a `"manual" install`_. 145 146 4. Optional steps: 147 148 * `Running the test suite`_ 149 * `Converting the documentation`_ 150 151 See also the OS-specific installation instructions below and 152 the `Docutils version repository`_ documentation. 153 154 * To install for a *specific Python version*, use this version in the 155 setup call, e.g. :: 156 157 python3.11 -m pip install docutils 158 159 If the python executable isn't on your path, you'll have to specify the 160 complete path, such as ``/usr/local/bin/python3.11``. 161 162 To install for different Python versions, repeat step 3 for every 163 required version. The last installed version will be used for the 164 ``docutils`` command line application. 165 166 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/ 167 .. _use pip for installing: 168 https://packaging.python.org/en/latest/tutorials/installing-packages/ 169 #use-pip-for-installing 170 .. _"editable" install: 171 https://pip.pypa.io/en/stable/topics/local-project-installs/ 172 #editable-installs 173 .. _"manual" install: docs/dev/repository.html#manual-install 174 175 176 GNU/Linux, BSDs, Unix, Mac OS X, etc. 177 ------------------------------------- 178 179 * Use ``su`` or ``sudo`` for a system-wide 180 installation as ``root``, e.g.:: 181 182 sudo pip install docutils 183 184 185 Windows 186 ------- 187 188 * The Python FAQ explains `how to run a Python program under Windows`__. 189 190 __ https://docs.python.org/3/faq/windows.html 191 #how-do-i-run-a-python-program-under-windows 192 193 * Usually, pip_ is automatically installed if you are using Python 194 downloaded from https://python.org. If not, see the 195 `pip documentation <https://pip.pypa.io/en/stable/installation/>`__. 196 197 * The command window should recognise the word ``py`` as an instruction to 198 start the interpreter, e.g. 199 200 py -m pip install docutils 201 202 If this does not work, you may have to specify the full path to the 203 Python executable. 204 205 206 Usage 207 ===== 208 209 Start the "docutils" command line application with:: 210 211 docutils [options] [<source> [<destination>]] 212 213 The default action is to convert a reStructuredText_ document to HTML5, 214 for example:: 215 216 docutils test.rst test.html 217 218 Read the ``--help`` option output for details on options and arguments and 219 `Docutils Front-End Tools`_ for the full documentation of the various tools. 220 221 For programmatic use of the `docutils` Python package, read the 222 `API Reference Material`_ and the source code. 223 Remaining questions may be answered in the `Docutils Project 224 Documentation`_ or the Docutils-users_ mailing list. 225 226 Contributions are welcome! 227 228 .. _reStructuredText: https://docutils.sourceforge.io/rst.html 229 .. _front-end scripts: 230 .. _Docutils Front-End Tools: docs/user/tools.html 231 .. _API Reference Material: /docs/index.html 232 #api-reference-material-for-client-developers 233 .. _Docutils Project Documentation: /docs/index.html 234 235 236 Project Files & Directories 237 =========================== 238 239 * README.rst: You're reading it. 240 241 * COPYING.rst: Public Domain Dedication and copyright details for 242 non-public-domain files (most are PD). 243 244 * FAQ.rst: Frequently Asked Questions (with answers!). 245 246 * RELEASE-NOTES.rst: Summary of the major changes in recent releases. 247 248 * HISTORY.rst: A detailed change log, for the current and all previous 249 project releases. 250 251 * BUGS.rst: Known bugs, and how to report a bug. 252 253 * THANKS.rst: List of contributors. 254 255 * pyproject.toml: Project metadata. 256 See "Installation" above. 257 258 * docutils: The project source directory, installed as a Python 259 package. 260 261 * docs: The project documentation directory. Read ``docs/index.rst`` 262 for an overview. 263 264 * docs/user: The project user documentation directory. Contains the 265 following documents, among others: 266 267 - docs/user/tools.rst: Docutils Front-End Tools 268 - docs/user/latex.rst: Docutils LaTeX Writer 269 - docs/user/rst/quickstart.rst: A ReStructuredText Primer 270 - docs/user/rst/quickref.html: Quick reStructuredText (HTML only) 271 272 * docs/ref: The project reference directory. 273 ``docs/ref/rst/restructuredtext.rst`` is the reStructuredText 274 reference. 275 276 * licenses: Directory containing copies of license files for 277 non-public-domain files. 278 279 * tools: Directory for Docutils front-end tools. See 280 ``docs/user/tools.rst`` for documentation. 281 282 * test: Unit tests. Not required to use the software, but very useful 283 if you're planning to modify it. See `Running the Test Suite`_ 284 below. 285 286 287 Development version 288 =================== 289 290 While we are trying to follow a "release early & often" policy, 291 features are added frequently. 292 We recommend using a current snapshot or a working copy of the repository. 293 294 Repository check-out: 295 To keep up to date on the latest developments, 296 use a `working copy`__ of the `Docutils version repository`_. 297 298 Snapshots: 299 To get a repository _`snapshot`, go to 300 https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ 301 and click the download snapshot button. 302 303 Unpack in a temporary directory, 304 **not** directly in Python's ``site-packages``. 305 306 See the `Installation`_ instructions above. 307 308 __ docs/dev/repository.html#checking-out-the-repository 309 .. _Docutils version repository: docs/dev/repository.html 310 .. _sandbox: https://docutils.sourceforge.io/sandbox/README.html 311 312 313 Converting the documentation 314 ============================ 315 316 After unpacking and installing the Docutils package, the following 317 shell commands will generate HTML for all included documentation:: 318 319 cd <archive_directory_path> 320 tools/buildhtml.py . 321 322 On Windows systems, type:: 323 324 cd <archive_directory_path> 325 py tools\buildhtml.py .. 326 327 The final directory name of the ``<archive_directory_path>`` is 328 "docutils" for snapshots. For official releases, the directory may be 329 called "docutils-X.Y.Z", where "X.Y.Z" is the release version. 330 331 Some files may generate system messages (warnings and errors). The 332 ``docs/user/rst/demo.rst`` file (under the archive directory) contains 333 five intentional errors. (They test the error reporting mechanism!) 334 335 336 Running the Test Suite 337 ====================== 338 339 The test suite is documented in `Docutils Testing`_ (docs/dev/testing.rst). 340 341 To run the entire test suite, open a shell and use the following 342 commands:: 343 344 cd <archive_directory_path>/test 345 ./alltests.py 346 347 Under Windows, type:: 348 349 cd <archive_directory_path>\test 350 python alltests.py 351 352 353 You should see a long line of periods, one for each test, and then a 354 summary like this:: 355 356 Ran 1744 tests in 5.859s 357 358 OK (skipped=1) 359 Elapsed time: 6.235 seconds 360 361 The number of tests will grow over time, and the times reported will 362 depend on the computer running the tests. 363 Some test are skipped, if optional dependencies (`recommendations`_) 364 are missing. 365 The difference between the two times represents the time required to set 366 up the tests (import modules, create data structures, etc.). 367 368 A copy of the test output is written to the file ``alltests.out``. 369 370 If any of the tests fail, please `open a bug report`_ or `send an email`_ 371 (see `Bugs <BUGS.html>`_). 372 Please include all relevant output, information about your operating 373 system, Python version, and Docutils version. To see the Docutils 374 version, look at the test output or use :: 375 376 docutils --version 377 378 .. _Docutils Testing: https://docutils.sourceforge.io/docs/dev/testing.html 379 .. _open a bug report: 380 https://sourceforge.net/p/docutils/bugs/ 381 .. _send an email: mailto:docutils-users@lists.sourceforge.net 382 ?subject=Test%20suite%20failure 383 .. _web interface: https://sourceforge.net/p/docutils/mailman/ 384 385 386 Getting Help 387 ============ 388 389 All documentation can be reached from the `Project Documentation 390 Overview`_. 391 392 The SourceForge `project page`_ has links to the tracker, mailing 393 lists, and code repository. 394 395 If you have further questions or need assistance with Docutils or 396 reStructuredText, please post a message to the Docutils-users_ mailing 397 list. 398 399 .. _Project Documentation Overview: docs/index.html 400 .. _project page: https://sourceforge.net/p/docutils 401 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users 402 403 404 .. Emacs settings 405 406 Local Variables: 407 mode: indented-text 408 mode: rst 409 indent-tabs-mode: nil 410 sentence-end-double-space: t 411 fill-column: 70 412 End: