{"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,"last_verified":"2026-05-12T13:12:53.291Z","next_check":"2026-06-26T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.4,"disk_size":"22.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.4,"disk_size":"23M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":3.9,"disk_size":"24.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":3.9,"disk_size":"25M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.8,"disk_size":"16.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.8,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.9,"disk_size":"16.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":3.9,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"21.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"22M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}