{"library":"sphinx","title":"Sphinx Documentation Generator","type":"library","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.","language":"python","status":"active","last_verified":"Tue May 19","install":{"commands":["pip install sphinx"],"cli":{"name":"sphinx-build","version":"sphinx-build 9.0.4"}},"imports":["from sphinx.application import Sphinx","from sphinx.cmd.build import main"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":"https://www.sphinx-doc.org/","github":"https://github.com/sphinx-doc/sphinx","docs":"https://www.sphinx-doc.org/","changelog":"https://www.sphinx-doc.org/en/master/changes.html","pypi":"https://pypi.org/project/sphinx/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null},"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.","tag":"stale","tag_description":"widespread failures or data too old to trust","last_tested":"2026-04-24","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}]},"compatibility":{"tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","last_tested":"2026-05-19","installed_version":"7.4.7","pypi_latest":"9.1.0","is_stale":true,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":5.4,"avg_import_s":0.55,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.51,"mem_mb":17.1,"disk_size":"92.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.3,"import_time_s":0.4,"mem_mb":17.1,"disk_size":"93M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.7,"mem_mb":18.4,"disk_size":"101.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.1,"import_time_s":0.66,"mem_mb":18.4,"disk_size":"102M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.57,"mem_mb":18.2,"disk_size":"92.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5,"import_time_s":0.63,"mem_mb":18.2,"disk_size":"93M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.55,"mem_mb":17.9,"disk_size":"92.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.9,"import_time_s":0.61,"mem_mb":18,"disk_size":"93M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","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":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":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":"sphinx","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.1,"import_time_s":0.4,"mem_mb":16.7,"disk_size":"92M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"sphinx","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":16.7,"disk_size":"92M"}]}}