{"id":710,"library":"sphinx","title":"Sphinx Documentation Generator","description":"Sphinx is a powerful Python documentation generator that creates intelligent and beautiful documentation from reStructuredText or Markdown sources. It is currently at version 9.1.0, with major releases typically annually and patch releases occurring frequently. It leverages Docutils for parsing and processing text, and is highly extensible.","status":"active","version":"9.1.0","language":"python","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinx","tags":["documentation","generator","restructuredtext","markdown","autodoc","tech-writing"],"install":[{"cmd":"pip install sphinx","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Sphinx 9.1.0 requires Python 3.12 or newer.","package":"python","optional":false},{"reason":"Sphinx uses Docutils as its parsing and translating suite. Version 9.1.0 requires Docutils 0.21 or newer.","package":"docutils","optional":false}],"imports":[{"note":"Used for programmatic access to the Sphinx application, such as building documentation.","symbol":"Sphinx","correct":"from sphinx.application import Sphinx"},{"note":"The entry point for the `sphinx-build` command-line tool, used for invoking builds. Less common for direct programmatic import than `Sphinx` application.","symbol":"main (sphinx-build)","correct":"from sphinx.cmd.build import main"}],"quickstart":{"code":"import os\nimport shutil\nfrom sphinx.application import Sphinx\nfrom sphinx.util.docutils import docutils_namespace\n\n# Define paths\nsource_dir = \"docs_src\"\nbuild_dir = os.path.join(source_dir, \"_build\")\noutput_html_dir = os.path.join(build_dir, \"html\")\ndoctrees_dir = os.path.join(build_dir, \".doctrees\")\n\n# Clean up previous build if exists\nif os.path.exists(source_dir):\n    shutil.rmtree(source_dir)\n\n# Create source directories\nos.makedirs(source_dir)\nos.makedirs(os.path.join(source_dir, \"_static\"))\nos.makedirs(os.path.join(source_dir, \"_templates\"))\n\n# Create a simple Python module to document\nmodule_path = os.path.join(source_dir, \"my_module.py\")\nwith open(module_path, \"w\") as f:\n    f.write(\"\"\"\ndef greet(name: str) -> str:\n    \"\"\"Greets the given name.\n\n    :param name: The name to greet.\n    :type name: str\n    :returns: A greeting string.\n    :rtype: str\n    \"\"\"\n    return f\"Hello, {name}!\"\n\nclass Greeter:\n    \"\"\"A simple greeter class.\n\n    :param greeting_word: The word to use for greeting.\n    :type greeting_word: str\n    \"\"\"\n    def __init__(self, greeting_word: str = \"Hello\"):\n        self.greeting_word = greeting_word\n\n    def wave(self, name: str) -> str:\n        \"\"\"Waves to the given name.\n\n        :param name: The name to wave to.\n        :type name: str\n        :returns: A waving greeting.\n        :rtype: str\n        \"\"\"\n        return f\"{self.greeting_word}, {name}! *waves*\"\n\"\"\")\n\n# Create conf.py\nconf_path = os.path.join(source_dir, \"conf.py\")\nwith open(conf_path, \"w\") as f:\n    f.write(\"\"\"\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Sphinx Project'\ncopyright = '2026, My Name'\nauthor = 'My Name'\nrelease = '0.1'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon', # for Google/NumPy style docstrings\n]\n\nhtml_theme = 'alabaster'\n\"\"\")\n\n# Create index.rst\nindex_path = os.path.join(source_dir, \"index.rst\")\nwith open(index_path, \"w\") as f:\n    f.write(\"\"\"\n.. _index:\n\nWelcome to My Sphinx Project!\n================================\n\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   modules\n\nThis is a sample project to demonstrate Sphinx documentation.\n\"\"\")\n\n# Create modules.rst for autodoc\nmodules_path = os.path.join(source_dir, \"modules.rst\")\nwith open(modules_path, \"w\") as f:\n    f.write(\"\"\"\nModule Documentation\n====================\n\n.. automodule:: my_module\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\"\"\")\n\ntry:\n    # Initialize and build the Sphinx application\n    # Use docutils_namespace to ensure clean Docutils state\n    with docutils_namespace():\n        app = Sphinx(\n            sourcedir=source_dir,\n            confdir=source_dir,\n            outdir=output_html_dir,\n            doctreedir=doctrees_dir,\n            buildername=\"html\",\n            freshenv=True,  # Re-read all files\n            warningiserror=False,\n            # status=sys.stdout, # Uncomment to see build status in console\n            # warning=sys.stderr, # Uncomment to see warnings in console\n        )\n        app.build(force_all=True)\n    print(f\"Documentation built successfully in {output_html_dir}\")\n    print(f\"Open file://{os.path.abspath(output_html_dir)}/index.html in your browser.\")\nexcept Exception as e:\n    print(f\"Error building documentation: {e}\")\n    import traceback\n    traceback.print_exc()\nfinally:\n    # Optional: Clean up created files and directories\n    # if os.path.exists(source_dir):\n    #     shutil.rmtree(source_dir)\n    pass\n","lang":"python","description":"This quickstart demonstrates how to programmatically build Sphinx documentation for a Python project. It creates a minimal project structure including `conf.py` (configuration), `index.rst` (main document), `my_module.py` (Python code), and `modules.rst` (autodoc entry), then invokes Sphinx to generate HTML output."},"warnings":[{"fix":"Upgrade your Python environment to 3.12 or higher, or pin your Sphinx dependency to `<9.1.0` if Python 3.11 support is critical.","message":"Sphinx 9.1.0 and later no longer support Python 3.11. Projects requiring Sphinx 9.1.0+ must use Python 3.12 or newer.","severity":"breaking","affected_versions":"9.1.0+"},{"fix":"Ensure that `docutils` is updated to version 0.21 or higher. Typically, `pip install sphinx` will handle this automatically, but manual intervention may be needed in environments with locked dependencies.","message":"Sphinx 9.1.0 and later require Docutils 0.21 or newer. Older Docutils versions (e.g., 0.20) are no longer supported.","severity":"breaking","affected_versions":"9.1.0+"},{"fix":"Custom Sphinx extensions that override or use `create_source_parser` must update their method signature to accept `config` and `env` parameters instead of `app`.","message":"The `create_source_parser` method in `SphinxComponentRegistry` had its signature changed in Sphinx 9.0.0. It no longer accepts an `app` parameter, but now requires `config` and `env`.","severity":"breaking","affected_versions":"9.0.0+"},{"fix":"Verify that all source files (e.g., `.rst`, `.md`, `.py` for autodoc) are correctly encoded (typically UTF-8) and do not contain characters that are invalid for their declared encoding.","message":"Starting with Sphinx 9.0.0, non-decodable characters in source files will raise an error, instead of being silently replaced with '?' (as in Sphinx 2.0-8.x).","severity":"breaking","affected_versions":"9.0.0+"},{"fix":"Refactor code interacting with autodoc options to use attribute access (e.g., `options.key`) rather than dictionary-style access (e.g., `options['key']`) to ensure forward compatibility.","message":"The mapping interface (dictionary-like access) for options objects in `sphinx.ext.autodoc` was deprecated in Sphinx 9.0.1. While still functional, it will be removed in a future major version.","severity":"deprecated","affected_versions":"9.0.1+"},{"fix":"Add the path to your Python project's root directory (or the directory containing the modules to be documented) to `sys.path` within your `conf.py` file, typically using `sys.path.insert(0, os.path.abspath('.'))` or `os.path.abspath('../..')` depending on your `conf.py` location.","message":"When using `sphinx.ext.autodoc` to document Python modules, Sphinx needs to be able to import your code. If your modules are not in a standard Python path, Sphinx will report 'module not found' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you encounter unexpected behavior or errors with custom extensions and `autodoc`, you can temporarily revert to the legacy implementation by setting `autodoc_use_legacy_class_based = True` in your `conf.py`. Report issues to the Sphinx project.","message":"The `sphinx.ext.autodoc` extension underwent a substantial rewrite in Sphinx 9.0.0. While most users should not see changes, extensions interacting with autodoc internals might be affected.","severity":"gotcha","affected_versions":"9.0.0+"},{"fix":"Review the specified line in your Python source file (e.g., `/script.py`, line 26 in the provided output) and correct any syntax errors. Ensure that your Python code is valid and can be executed by the Python interpreter.","message":"Your Python source file contains a `SyntaxError: invalid syntax`, preventing the Python interpreter from parsing your code. This means Sphinx cannot import or process your project's modules.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the Python code in your script at the indicated line number (e.g., line 24 in `/script.py`) and surrounding lines to correct the syntax error. Ensure all string literals, function calls, and statements are correctly formed according to Python syntax rules. Pay attention to commas, parentheses, and string delimiters.","message":"The build process failed due to a `SyntaxError` in the user's script (e.g., `script.py`), indicating a malformed Python statement or incorrect string literal declaration. This error occurs within the custom script and is not a direct result of Sphinx or dependency changes.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:04:30.598Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure Sphinx is installed (`pip install sphinx`) and your virtual environment is activated, or verify that the Python scripts directory containing `sphinx-build` is included in your system's PATH.","cause":"The `sphinx-build` command is not in the system's PATH, usually because Sphinx was not installed in the active Python environment or its scripts directory is not accessible.","error":"sphinx-build: command not found"},{"fix":"Rename duplicate labels in your source files to ensure each label used for internal linking is unique across the entire Sphinx project.","cause":"Multiple reStructuredText or Markdown labels with the same name exist across your project, preventing Sphinx from uniquely identifying them for cross-referencing.","error":"WARNING: Duplicate label"},{"fix":"Install the missing theme or extension package using pip: `pip install sphinx_rtd_theme` (or the appropriate package name).","cause":"The Python package for the specified Sphinx theme or extension (e.g., `sphinx_rtd_theme`) is not installed in the active Python environment where Sphinx is being run.","error":"ModuleNotFoundError: No module named 'sphinx_rtd_theme'"},{"fix":"Examine the full traceback provided after the error message to locate the specific line and nature of the error in `conf.py` and correct the Python code or configuration value.","cause":"There is a Python error (e.g., syntax error, `NameError`, or incorrect configuration value) within your `conf.py` configuration file, preventing Sphinx from loading its settings.","error":"Sphinx error: An exception occurred in conf.py"},{"fix":"Add the parent directory of your module to `sys.path` in your `conf.py` file, typically using `import os, sys; sys.path.insert(0, os.path.abspath('.'))` or `os.path.abspath('../../')`.","cause":"Sphinx's `autodoc` extension cannot find the specified Python module because the path to your project's source code is not correctly included in `sys.path` within `conf.py`.","error":"WARNING: autodoc: failed to import module 'your_module_name' from its path"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"9.1.0","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":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":17.1,"disk_size":"92.1M"},{"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.5,"mem_mb":17.1,"disk_size":"91.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.2,"import_time_s":0.39,"mem_mb":17.1,"disk_size":"93M"},{"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.39,"mem_mb":17.1,"disk_size":"92M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":18.4,"disk_size":"101.3M"},{"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.77,"mem_mb":18.5,"disk_size":"101.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.4,"import_time_s":0.6,"mem_mb":18.4,"disk_size":"102M"},{"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.58,"mem_mb":18.5,"disk_size":"102M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.55,"mem_mb":18.2,"disk_size":"92.2M"},{"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.61,"mem_mb":18.2,"disk_size":"92.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.1,"import_time_s":0.74,"mem_mb":18.2,"disk_size":"93M"},{"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.78,"mem_mb":18.2,"disk_size":"92M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":17.9,"disk_size":"92.1M"},{"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.56,"mem_mb":18,"disk_size":"91.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.6,"import_time_s":0.59,"mem_mb":17.9,"disk_size":"93M"},{"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.58,"mem_mb":18,"disk_size":"92M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":16.7,"disk_size":"91.4M"},{"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.43,"mem_mb":16.7,"disk_size":"91.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.3,"import_time_s":0.41,"mem_mb":16.7,"disk_size":"92M"},{"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.37,"mem_mb":16.7,"disk_size":"92M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}