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:

  • curl
  • wget
  • httpie
  • requests

• Custom builders, such as the @plone/client package, 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.