{"id":348,"library":"docutils","title":"Docutils: Python Documentation Utilities","description":"Docutils is a modular system for processing plaintext documentation into useful formats, such as HTML, LaTeX, and XML. The current version is 0.22.4, released on March 28, 2026. Docutils follows a regular release cadence, with major releases introducing new features and minor releases focusing on bug fixes and improvements.","status":"active","version":"0.22.4","language":"python","source_language":"en","source_url":"https://github.com/docutils/docutils","tags":["documentation","reStructuredText","Python","markup"],"install":[{"cmd":"pip install docutils","lang":"bash","label":"Install Docutils"}],"dependencies":[],"imports":[{"note":"Ensure correct import path to avoid ImportError.","symbol":"Publisher","correct":"from docutils.core import Publisher"},{"note":"Ensure correct import path to avoid ImportError.","symbol":"Reader","correct":"from docutils.readers.standalone import Reader"},{"note":"Ensure correct import path to avoid ImportError.","symbol":"Writer","correct":"from docutils.writers.html4css1 import Writer"}],"quickstart":{"code":"import os\nfrom docutils.core import publish_string\nfrom docutils.readers.standalone import Reader\nfrom docutils.writers.html4css1 import Writer\n\n# Sample reStructuredText input\nrst_input = '''\nTitle\n=====\n\nThis is a sample reStructuredText document.\n'''\n\n# Create Reader and Writer instances\nreader = Reader()\nwriter = Writer()\n\n# Process the input\noutput = publish_string(source=rst_input.encode('utf-8'), reader=reader, writer=writer)\n\n# Print the HTML output\nprint(output.decode('utf-8'))","lang":"python","description":"This script demonstrates how to convert a reStructuredText document to HTML using Docutils. It imports the necessary modules, defines a sample reStructuredText input, and processes it to produce HTML output."},"warnings":[{"fix":"Upgrade to Python 3.9 or later to continue receiving support.","message":"Docutils 0.20 is the last version supporting Python 3.7 and 3.8.","severity":"breaking","affected_versions":"0.20"},{"fix":"Use the 'docutils' command-line tool instead.","message":"The 'rst2html.py' script is deprecated and will be removed in a future release.","severity":"deprecated","affected_versions":"0.22.4"},{"fix":"Install Docutils using 'pip install docutils'.","message":"Ensure that the 'docutils' package is installed in your Python environment to avoid ImportError.","severity":"gotcha","affected_versions":"0.22.4"}],"env_vars":null,"search_vec":"'0.22.4':27 '2026':32 '28':31 'bug':50 'cadenc':38 'current':24 'document':3,13,54 'docutil':1,5,33 'featur':44 'fix':51 'focus':48 'follow':34 'format':16 'html':19 'improv':53 'introduc':42 'latex':20 'major':40 'march':30 'markup':57 'minor':46 'modular':8 'new':43 'plaintext':12 'process':11 'python':2,56 'regular':36 'releas':28,37,41,47 'restructuredtext':55 'system':9 'use':15 'util':4 'version':25 'xml':22","created_at":"2026-03-28T10:51:36.226296+00:00","updated_at":"2026-04-16T14:40:02.209380+00:00","problems":[{"fix":"Install docutils using pip: `pip install docutils`","cause":"The `docutils` library is not installed in the Python environment or the Python interpreter cannot find it in the `PATH`.","error":"ModuleNotFoundError: No module named 'docutils'"},{"fix":"Upgrade Sphinx to version 3.0 or later: `pip install --upgrade sphinx` or pin `docutils` to an older compatible version, e.g., `docutils<0.18`.","cause":"This error often occurs due to an incompatibility between older versions of Sphinx (before 3.0) and `docutils` version 0.18 or later, where Sphinx is using `docutils` for reStructuredText parsing.","error":"TypeError: 'generator' object is not subscriptable"},{"fix":"Ensure `docutils` is installed for the correct Python interpreter: `pip install docutils`. If using a virtual environment, activate it before installing. If system-wide tools are pointing to a different Python, adjust the PATH or shebangs.","cause":"This specific import error usually indicates that `docutils` is either not correctly installed, or there's an issue with the Python environment's ability to locate the installed package.","error":"ImportError: No module named docutils.core"},{"fix":"Update any code that imports from `docutils.utils.error_reporting` to use the new error handling mechanisms in `docutils` 0.22+, or temporarily downgrade `docutils` to a version prior to 0.22 if an immediate fix is needed for a dependent library.","cause":"The `docutils.utils.error_reporting` module was removed or refactored in `docutils` version 0.22, leading to this error when older code attempts to import from it.","error":"ModuleNotFoundError: No module named 'docutils.utils.error_reporting'"},{"fix":"Check the specified version for correctness. Try installing without a version constraint (`pip install docutils`) to get the latest compatible version. If a specific older version is required, verify its availability for your Python version and architecture. Also, check network connectivity and proxy settings if applicable.","cause":"This error occurs when `pip` cannot find a distribution for the specified version (X.Y) of `docutils` for the current Python version and operating system. This can be due to a typo in the version, the version being too old/new, or network issues preventing access to PyPI.","error":"ERROR: Could not find a version that satisfies the requirement docutils==X.Y (from versions: none) ERROR: No matching distribution found for docutils==X.Y"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"0.23","cli_name":"rst2html","cli_version":"rst2html (Docutils 0.22.4, Python 3.11.15, on linux)","type":"library","homepage":"https://docutils.sourceforge.io","github":null,"docs":"https://docutils.sourceforge.io/docs/","changelog":"https://docutils.sourceforge.io/HISTORY.html","pypi":"https://pypi.org/project/docutils/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}