sphinxcontrib-httpexample
sphinxcontrib-httpexample is a Sphinx domain extension for describing RESTful HTTP APIs in detail.
It enhances sphinxcontrib-httpdomain with a simple call example directive.
The directive provided by this extension generates RESTful HTTP API call examples for different HTTP clients from a single HTTP request example.
The audience for this extension are developers and technical writers documenting their RESTful HTTP APIs.
This extension was originally developed for documenting plone.restapi.
Features
-
Directive for generating various RESTful HTTP API call examples from a single HTTP request.
-
Supported HTTP clients:
-
Custom builders, such as the
@plone/clientpackage, an agnostic library that provides easy access to the Plone REST API from a client written in TypeScript. See https://sphinxcontrib-httpexample.readthedocs.io/en/latest/custom.html for examples.
Examples
This extension has been used in documentation for the following projects and probably other similar projects as well.
- https://6.docs.plone.org/plone.restapi/docs/source/index.html
- https://sphinxcontrib-httpexample.readthedocs.io/en/latest/
- https://guillotina.readthedocs.io/en/latest/
Documentation
Full documentation for end users can be found in the docs folder.
It's also available online at https://sphinxcontrib-httpexample.readthedocs.io/en/latest/.
Installation
Add sphinxcontrib-httpexample and sphincontrib-httpdomain to your project requirements.
Then configure your Sphinx configuration file conf.py with sphinxcontrib.httpdomain and sphinxcontrib.httpexample as follows.
extensions = [
"sphinxcontrib.httpdomain",
"sphinxcontrib.httpexample",
]
Contribute
To contribute to sphinxcontrib-httpexample, first set up your environment.
Set up development environment
Install uv. Carefully read the console output for further instruction.
curl -LsSf https://astral.sh/uv/install.sh | sh
Initialize a Python virtual environment.
uv venv
Install sphinxcontrib-httpexample.
uv sync
Build documentation
Rebuild Sphinx documentation on changes, with live reload in the browser.
make livehtml
To stop the preview, type CTRL-C.
Run tests
make test
License
The project is licensed under the GPLv2.
4 maintainers
Metadata
4 maintainers
Release files for sphinxcontrib-httpexample 2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sphinxcontrib_httpexample-2.0.tar.gz | 113.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinxcontrib_httpexample-2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 127.3 kB
Release files / sphinxcontrib_httpexample-2.0.tar.gz
| Download URL | sphinxcontrib_httpexample-2.0.tar.gz |
|---|---|
| Size | 113.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
881881e0125e0f75c15e46564a82252dd8a68c499348d2d9e42cd52c213a58ad
|
|
BLAKE2b-256 checksum How to use checksums |
4297a2d11c63399e777f3013c508b1c7147cea86f10ebfa13f22b0f27e104c88
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.14.0
|
Release files / sphinxcontrib_httpexample-2.0-py3-none-any.whl
| Download URL | sphinxcontrib_httpexample-2.0-py3-none-any.whl |
|---|---|
| Size | 13.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4e73ffc3e137816cb08947acc6210eaf0ea6a21400e0bc51e142a2a9b8ceecdc
|
|
BLAKE2b-256 checksum How to use checksums |
d4d6decba4e0db46c23fe098e82c821c714391b436a30fc3df18dea253bf9653
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.14.0
|
