{"id":2775,"library":"sphinxcontrib-httpdomain","title":"Sphinx HTTP Domain","description":"Sphinxcontrib-httpdomain is an active Sphinx extension (current version 2.0.0) that provides a domain for documenting RESTful HTTP APIs directly within reStructuredText or MyST documentation. It allows authors to describe HTTP resources, methods, request/response headers, query parameters, and status codes, integrating API documentation seamlessly with project documentation. Releases are made as needed, often tied to Sphinx compatibility or feature additions.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/httpdomain","tags":["Sphinx","extension","documentation","HTTP","API","REST","autodoc"],"install":[{"cmd":"pip install sphinxcontrib-httpdomain","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core documentation generator that this library extends.","package":"Sphinx"},{"reason":"Requires Python 3.10 or newer.","package":"Python","optional":false}],"imports":[{"note":"This is a Sphinx extension; it's enabled by adding its name to the 'extensions' list in Sphinx's conf.py, not by a Python import statement for direct use.","wrong":"import sphinxcontrib.httpdomain","symbol":"Extension Configuration","correct":"extensions = ['sphinxcontrib.httpdomain']"}],"quickstart":{"code":"Add `sphinxcontrib.httpdomain` to your `conf.py`:\n\n```python\n# conf.py\nproject = 'My API Docs'\ncopyright = '2026, Your Name'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.httpdomain'\n]\n```\n\nThen, in a reStructuredText file (e.g., `api.rst`):\n\n```rst\n.. http:get:: /users/(int:user_id)\n   :synopsis: Get user profile\n\n   Fetches the profile for a specific user.\n\n   :param user_id: The ID of the user to retrieve.\n   :type user_id: int\n   :status 200: User profile retrieved successfully.\n   :status 404: User not found.\n\n   **Example request**:\n\n   .. sourcecode:: http\n\n      GET /users/123 HTTP/1.1\n      Host: example.com\n      Accept: application/json\n\n   **Example response**:\n\n   .. sourcecode:: http\n\n      HTTP/1.1 200 OK\n      Content-Type: application/json\n\n      {\n          \"id\": 123,\n          \"name\": \"John Doe\",\n          \"email\": \"john.doe@example.com\"\n      }\n```","lang":"python+rst","description":"To use sphinxcontrib-httpdomain, first add 'sphinxcontrib.httpdomain' to the 'extensions' list in your Sphinx project's `conf.py`. Then, you can define HTTP API endpoints using directives like `.. http:get::` in your reStructuredText or MyST files, detailing paths, parameters, statuses, and examples."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer, or pin to an older `sphinxcontrib-httpdomain` version (e.g., `<2.0.0`) if Python upgrade is not feasible.","message":"Version 2.0.0 requires Python >=3.10. Users on older Python versions (e.g., 3.7-3.9) must upgrade their Python environment to use this version of the extension.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace `:mimetype:` with `:http:header:` in your documentation. For example, `:mimetype:`text/html`` becomes `:http:header:`Content-Type```.","message":"The `mimetype` role was deprecated in version 1.3.0. Use the `http:header` role instead for referring to MIME types or HTTP headers.","severity":"deprecated","affected_versions":"<1.3.0 (usage)"},{"fix":"Review your documentation and consider custom Sphinx validation if you relied on `http_strict_mode` for warnings about non-standard header prefixes.","message":"The `http_strict_mode` configuration option's behavior changed in version 1.5.0. It no longer warns on non-standard header prefixes, potentially leading to fewer warnings than expected if strict mode was relied upon for such validation.","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"If encountering parallel build errors, try disabling parallel builds in Sphinx (e.g., `make html -j1` or setting `num_workers = 1` in `conf.py`). Monitor GitHub issues for a permanent fix.","message":"Users have reported 'routingtable not defined' errors during parallel Sphinx builds, indicating potential issues with concurrency when building documentation with this extension.","severity":"gotcha","affected_versions":"All versions (intermittent)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}