Sphinx HTTPDomain

https://github.com/sphinx-contrib/httpdomain
Admin
Sphinx HTTPDomain is a Sphinx extension that provides a domain for documenting and describing HTTP...
Tokens:16,033
Snippets:160
Trust Score:9.5
License:BSD-3-Clause
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install development environment

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Configures the Python virtual environment and installs dependencies using the project's Makefile.

```shell
make dev
```

--------------------------------

### HTTP Request Example

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

An example of an HTTP GET request.

```APIDOC
## HTTP Request Example

### Description
Example of a GET request to retrieve user posts.

### Request Example
```http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
```
```

--------------------------------

### HTTP Request and Response Examples

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Examples of raw HTTP request and response blocks.

```http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
```

```http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  },
  {
    "post_id": 12346,
    "author_id": 123,
    "tags": ["html5", "standards", "web"],
    "subject": "We go to HTML 5"
  }
]
```

--------------------------------

### Tornado Application Example

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Example of a basic Tornado web application with multiple handlers. This demonstrates how to define routes for different API endpoints.

```python
from tornado.web import Application, RequestHandler, url

class MainHandler(RequestHandler):
    def get(self):
        """Home page."""
        self.write('home')

class UserHandler(RequestHandler):
    def get(self, user):
        """User profile page.

        :param user: user login name
        :status 200: when user exists
        :status 404: when user doesn't exist
        """
        self.write('hi, ' + user)

class UserPostHandler(RequestHandler):
    def get(self, user, post_id):
        """User's post.

        :param user: user login name
        :param post_id: post unique id
        :status 200: when user and post exists
        :status 404: when user or post doesn't exist
        """
        self.write(f'{post_id} by {user}')

app = Application([
    url(r'/', MainHandler),
    url(r'/(?P<user>[a-z0-9]+)', UserHandler),
    url(r'/(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)', UserPostHandler),
])
```

--------------------------------

### HTTP Response Example

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

An example of a successful HTTP response with JSON content.

```APIDOC
## HTTP Response Example

### Description
Example of a 200 OK response containing a list of posts.

### Response Example
```json
[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  },
  {
    "post_id": 12346,
    "author_id": 123,
    "tags": ["html5", "standards", "web"],
    "subject": "We go to HTML 5"
  }
]
```
```

--------------------------------

### GET /

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Retrieves the home page.

```APIDOC
## GET /

### Description
Home page.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **body** (string) - Returns 'home'
```

--------------------------------

### GET /short-syntax Endpoint

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Demonstrates a shorter syntax for documenting API responses, including headers and JSON bodies.

```APIDOC
## GET /short-syntax

### Description
This endpoint demonstrates a concise way to document API responses.

### Method
GET

### Endpoint
/short-syntax

### Request
#### Headers
- **Accept**: `application/json`

### Response
#### Success Response (200)
- **foo** (string) - Foo key value
- **bar** (number) - Bar key value
- **baz** (array of strings) - Some baz field

#### Response Example
```json
{
  "foo": "string",
  "bar": 123,
  "baz": ["string1", "string2"]
}
```
```

--------------------------------

### GET /foo Endpoint

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Documentation for the GET /foo endpoint, including query parameters and status codes.

```APIDOC
## GET /foo

### Description
This endpoint retrieves information about a resource.

### Method
GET

### Endpoint
/foo

### Parameters
#### Query Parameters
- **resource** (string) - Required - Description for ``resource``

### Response
#### Success Response (200)
- Description for 200
#### Error Response (404)
- Description for 404
```

--------------------------------

### HTTP GET Directive with Addtoc Option

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Example of using the 'addtoc' option to include HTTP API endpoint details in the page-level table of contents.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :addtoc:
```

--------------------------------

### HTTP GET Directive with Synopsis Option

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Illustrates adding a short description to an HTTP GET endpoint in the routing table using the 'synopsis' option.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by the specified tag for the user
```

--------------------------------

### GET /bar Endpoint

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Documentation for the GET /bar endpoint, with an option to exclude it from indexing.

```APIDOC
## GET /bar

### Description
This endpoint retrieves data but is not indexed.

### Method
GET

### Endpoint
/bar

### Options
- **noindex**: Excludes this endpoint from indexing.
```

--------------------------------

### HTTP GET Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Documents a GET endpoint with URL parameters, query parameters, headers, and status codes.

```APIDOC
## GET /users/(int:user_id)/posts/(tag)

### Description
Retrieves posts tagged with `tag` written by the specified user.

### Method
GET

### Endpoint
/users/(int:user_id)/posts/(tag)

#### Query Parameters
- **sort** (string) - Optional - one of ``hit``, ``created-at``
- **offset** (int) - Optional - offset number. default is 0
- **limit** (int) - Optional - limit number. default is 30

#### Request Headers
- **Host** (string) - Required - example.com
- **Accept** (string) - Required - the response content type depends on Accept header

#### Response Headers
- **Content-Type** (string) - Description: this depends on Accept header of request

#### Success Response (200)
- **post_id** (int) - Description: The unique identifier for the post.
- **author_id** (int) - Description: The unique identifier for the author.
- **tags** (array of strings) - Description: A list of tags associated with the post.
- **subject** (string) - Description: The subject or title of the post.

### Request Example
```http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json
```

### Response Example
```http
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  }
]
```

#### Status Codes
- **200** - no error
- **404** - user not found
```

--------------------------------

### Check Current Version with uv

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/RELEASE.md

Use this command to check the current version of uv installed in your environment.

```shell
uv version
```

--------------------------------

### Document HTTP GET Endpoints

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Use the http:get directive to define GET endpoints, including query parameters, headers, and status codes.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)

   Retrieves posts tagged with `tag` written by the specified user.

   **Example request**:

   .. sourcecode:: http

      GET /users/123/posts/web HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      [
        {
          "post_id": 12345,
          "author_id": 123,
          "tags": ["server", "web"],
          "subject": "I tried Nginx"
        }
      ]

   :query sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on Accept header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on Accept header of request
   :statuscode 200: no error
   :statuscode 404: user not found
```

--------------------------------

### GET /{user}

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Retrieves the user profile page.

```APIDOC
## GET /{user}

### Description
User profile page.

### Method
GET

### Endpoint
/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name

### Response
#### Success Response (200)
- **status** - when user exists

#### Error Response (404)
- **status** - when user doesn't exist
```

--------------------------------

### Referencing HTTP GET Directive

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Example of referencing an HTTP GET directive within reStructuredText. This is useful for linking to specific API endpoints.

```rst
:http:get:`/users/(int:user_id)/posts/(tag)`
```

--------------------------------

### HTTP GET Directive with Noindex Option

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Demonstrates how to use the 'noindex' option with an HTTP GET directive to exclude it from the routing table.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :noindex:
```

--------------------------------

### HTTP Cross-Reference Roles

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Create hyperlinks to documented endpoints and reference HTTP concepts using roles like :http:get:, :http:method:, :http:statuscode:, :http:header:, and :mimetype:.

```APIDOC
## HTTP Cross-Reference Roles

Create hyperlinks to documented endpoints and reference HTTP concepts.

See :http:get:`/users/(int:user_id)/posts/(tag)` for retrieving user posts.

After creation, you will be redirected to :http:get:`/posts/(int:post_id)`.

This endpoint uses :http:method:`POST` for data submission.

Returns :http:statuscode:`404` when the resource is not found.
Returns :http:statuscode:`200 OK` on success.

The :http:header:`Content-Type` header must be set to :mimetype:`application/json`.
```

--------------------------------

### HTTP GET Directive with Deprecated Option

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Shows how to mark an HTTP GET method as deprecated in the routing table using the 'deprecated' option.

```rst
.. http:get:: /users/(int:user_id)/tagged_posts
   :deprecated:
```

--------------------------------

### Define HTTP GET Endpoint with Parameters

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

This reStructuredText directive defines an HTTP GET endpoint. It includes path parameters like 'user_id' (integer) and 'tag' (string), along with query parameters and request/response headers.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)

   The posts tagged with `tag` that the user (`user_id`) wrote.

   **Example request**:

   .. sourcecode:: http

      GET /users/123/posts/web HTTP/1.1
      Host: example.com
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: text/javascript

      [
        {
          "post_id": 12345,
          "author_id": 123,
          "tags": ["server", "web"],
          "subject": "I tried Nginx"
        },
        {
          "post_id": 12346,
          "author_id": 123,
          "tags": ["html5", "standards", "web"],
          "subject": "We go to HTML 5"
        }
      ]

   :query sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :statuscode 200: no error
   :statuscode 404: there's no user
```

--------------------------------

### Referencing Routing Table in reStructuredText

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Example of how to reference the automatically generated HTTP routing table in reStructuredText documentation. Use the :ref:`routingtable` directive.

```rst
See the complete API reference in the :ref:`routingtable`.

For a full list of all endpoints, refer to :ref:`routingtable`.
```

--------------------------------

### GET /{user}/posts/{post_id}

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Retrieves a specific post for a user.

```APIDOC
## GET /{user}/posts/{post_id}

### Description
User's post.

### Method
GET

### Endpoint
/{user}/posts/{post_id}

### Parameters
#### Path Parameters
- **user** (string) - Required - user login name
- **post_id** (integer) - Required - post unique id

### Response
#### Success Response (200)
- **status** - when user and post exists

#### Error Response (404)
- **status** - when user or post doesn't exist
```

--------------------------------

### Document HTTP endpoints

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use http:post and http:get directives to define API endpoints, including parameters, headers, and status codes.

```rst
.. http:post:: /posts/(int:post_id)

   Replies a comment to the post.

   :param post_id: post's unique id
   :type post_id: int
   :form email: author email address
   :form body: comment body
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :status 302: and then redirects to :http:get:`/posts/(int:post_id)`
   :status 400: when form parameters are missing

.. http:get:: /posts/(int:post_id)

   Fetches the post

   (...)
```

--------------------------------

### GET /users/(int:user_id)/posts/(tag)

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Retrieves a list of posts for a specific user filtered by a tag.

```APIDOC
## GET /users/(int:user_id)/posts/(tag)

### Description
Retrieves a list of posts for a specific user filtered by a tag.

### Method
GET

### Endpoint
/users/(int:user_id)/posts/(tag)

### Parameters
#### Path Parameters
- **user_id** (int) - Required - The ID of the user.
- **tag** (string) - Required - The tag to filter posts by.

#### Query Parameters
- **sort** (string) - Optional - One of 'hit', 'created-at'.
- **offset** (number) - Optional - Offset number, default is 0.
- **limit** (number) - Optional - Limit number, default is 30.

### Request Headers
- **Accept** - The response content type.
- **Authorization** - Optional OAuth token.

### Response
#### Success Response (200)
- **post_id** (int) - The ID of the post.
- **author_id** (int) - The ID of the author.
- **tags** (array) - List of tags associated with the post.
- **subject** (string) - The subject of the post.

#### Response Example
[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  },
  {
    "post_id": 12346,
    "author_id": 123,
    "tags": ["html5", "standards", "web"],
    "subject": "We go to HTML 5"
  }
]
```

--------------------------------

### Publish Project with uv

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/RELEASE.md

Use the uv publish command to upload your project to PyPI. Ensure you have your personal access token configured.

```shell
uv publish
```

--------------------------------

### List available Make commands

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Displays all supported commands defined in the Makefile.

```shell
make help
```

--------------------------------

### Navigate to the repository directory

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Change the current working directory to the project folder.

```shell
cd httpdomain
```

--------------------------------

### Run tests and build documentation

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Executes tests and documentation builds using tox.

```shell
tox r
```

```shell
tox r -e py314
```

--------------------------------

### Build Project Distribution

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/RELEASE.md

Run the make dist command to clean the dist directory and build the project's distribution files.

```shell
make dist
```

--------------------------------

### Clone the httpdomain repository

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use these commands to download the source code from the official repository.

```console
$ git clone https://github.com/sphinx-contrib/httpdomain.git
$ cd httpdomain
```

--------------------------------

### Documentation and environment management commands

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Commands for managing the documentation build process and cleaning the environment.

```shell
make livehtml
```

```shell
make clean
```

```shell
make init
```

--------------------------------

### Clone the httpdomain repository

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/CONTRIBUTING.md

Initial step to obtain the source code from GitHub.

```shell
git clone https://github.com/sphinx-contrib/httpdomain.git
```

--------------------------------

### Typed Query Parameter Description

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Demonstrates how to define typed query parameters for an HTTP resource, specifying their type and description.

```rst
:query string title: the post title
:query string body: the post body
:query boolean sticky: whether it's sticky or not
```

--------------------------------

### Qrefflask Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Generates a quick reference table with links to full API documentation for Flask applications.

```APIDOC
## Qrefflask Directive - Quick Reference Table

Generates a quick reference table with links to full API documentation.

.. qrefflask:: myapp:app
   :undoc-static:

.. qrefflask:: myapp:app
   :autoquickref:
```

```python
# conf.py - Enable both extensions
extensions = [
    'sphinxcontrib.autohttp.flask',
    'sphinxcontrib.autohttp.flaskqref'
]
```

--------------------------------

### Dry Run Version Bump with uv

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/RELEASE.md

Before bumping the version, use the --dry-run flag to preview the changes that uv will make. Replace <args> with the appropriate versioning arguments.

```shell
uv bump --dry-run <args>
```

--------------------------------

### Configure HTTP Directive Options

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Directives demonstrating optional configurations like indexing, synopses, and deprecation status.

```rst
.. http:get:: /bar
   :noindex:
```

```rst
.. http:put:: /baz
   :synopsis: Something special
```

```rst
.. http:post:: /baz
   :deprecated:
   :synopsis: Something special, but use PUT instead
```

```rst
.. http:options:: /baz
   :addtoc:
```

--------------------------------

### Autobottle Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generates API documentation from a Bottle application's routing table.

```APIDOC
## Autobottle Directive - Automatic Bottle API Documentation

Automatically generates API documentation from a Bottle application.

.. autobottle:: myapp:app

.. autobottle:: myapp:app
   :endpoints: user, post
   :undoc-endpoints: admin
   :include-empty-docstring:
```

```python
# myapp.py - Bottle application
from bottle import route, default_app

@route('/')
def home():
    """Home page."""
    return 'home'

@route('/<user>')
def user(user):
    """User profile page.

    :param user: user login name
    :status 200: when user exists
    :status 404: when user doesn't exist
    """
    return 'hi, ' + user

@route('/<user>/posts/<post_id:int>')
def post(user, post_id):
    """User's post.

    :param user: user login name
    :param post_id: post unique id
    :status 200: when user and post exists
    :status 404: when user or post doesn't exist
    """
    return f'{post_id} by {user}'

app = default_app()
```

--------------------------------

### Directive: autobottle

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Generates HTTP API references from a Bottle application by importing the application object.

```APIDOC
## .. autobottle:: module:app

### Description
Generates HTTP API references from a Bottle application. It takes an import name, where a colon separates the module path and the application variable or factory function.

### Options
- **endpoints** (list) - Optional - Specific endpoints to document. If omitted, all endpoints are documented.
- **undoc-endpoints** (list) - Optional - Endpoints to exclude from the generated documentation.
- **include-empty-docstring** (flag) - Optional - Include view functions that do not have a docstring.
```

--------------------------------

### Configure Sphinx HTTPDomain

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Add the extension to the extensions list in your conf.py file and optionally configure index settings.

```python
# conf.py
extensions = ['sphinxcontrib.httpdomain']

# Optional configuration settings
http_index_ignore_prefixes = ['/internal', '/_proxy']
http_index_shortname = 'api'
http_index_localname = "My Project HTTP API"
http_strict_mode = True  # Emit errors for non-standard status codes/methods
```

--------------------------------

### Generate Flask API Quick Reference Table

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use the .. qrefflask:: directive to generate a quick API reference table for your Flask application. This directive can be used with options like ':undoc-static:' to control which elements are included.

```rst
.. qrefflask:: autoflask_sampleapp:app
   :undoc-static:
```

--------------------------------

### Autobottle Directive Usage

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generate API documentation from Bottle applications.

```rst
.. autobottle:: myapp:app

.. autobottle:: myapp:app
   :endpoints: user, post
   :undoc-endpoints: admin
   :include-empty-docstring:
```

```python
# myapp.py - Bottle application
from bottle import route, default_app

@route('/')
def home():
    """Home page."""
    return 'home'

@route('/<user>')
def user(user):
    """User profile page.

    :param user: user login name
    :status 200: when user exists
    :status 404: when user doesn't exist
    """
    return 'hi, ' + user

@route('/<user>/posts/<post_id:int>')
def post(user, post_id):
    """User's post.

    :param user: user login name
    :param post_id: post unique id
    :status 200: when user and post exists
    :status 404: when user or post doesn't exist
    """
    return f'{post_id} by {user}'

app = default_app()
```

--------------------------------

### OPTIONS /baz Endpoint

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Documentation for the OPTIONS /baz endpoint.

```APIDOC
## OPTIONS /baz

### Description
This endpoint retrieves options for the /baz resource.

### Method
OPTIONS

### Endpoint
/baz

### Options
- **addtoc**: Adds this endpoint to a table of contents.
```

--------------------------------

### Flask Quick API Reference Generation

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

This section details the directives and options for generating quick API references from Flask applications using sphinxcontrib.autohttp.flaskqref.

```APIDOC
## .. qrefflask:: directive

### Description
Generates a quick API reference table for the route documentation produced by :mod:`sphinxcontrib.autohttp.flask`.

### Method
N/A (Directive)

### Endpoint
N/A (Directive)

### Parameters
#### Directive Options
- **autoquickref** (flag) - If used, all routes must be inside blueprints. The resource name will be the blueprint's name, and the short description will be the first line of the docstring.

#### Route Docstring Annotation
- **.. :quickref:** [<resource>;] <short description>
  - **<resource>** (string, optional) - The resource name of the operation. Used for grouping.
  - **<short description>** (string) - A brief description of what the operation does.

### Request Example
```rst
.. qrefflask:: autoflask_sampleapp:app
   :undoc-static:
```

### Response
N/A (Generates tables within documentation)
```

--------------------------------

### Qrefflask Directive Usage

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Generate quick reference tables for Flask applications and configure the extension in conf.py.

```rst
.. qrefflask:: myapp:app
   :undoc-static:

.. qrefflask:: myapp:app
   :autoquickref:
```

```python
# conf.py - Enable both extensions
extensions = [
    'sphinxcontrib.autohttp.flask',
    'sphinxcontrib.autohttp.flaskqref'
]
```

--------------------------------

### Use the autoflask Directive

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Include the autoflask directive in your documentation to generate API references from a Flask app.

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:
```

--------------------------------

### Document Flask Applications

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Directives for auto-generating documentation from Flask applications with various configuration options.

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:
```

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:
   :endpoints:
   :undoc-endpoints:
   :undoc-blueprints:
```

```rst
.. autoflask:: autoflask_sampleapp:app
   :undoc-static:
   :endpoints:
   :undoc-endpoints:
   :undoc-blueprints:
   :order: path
```

```rst
.. autoflask:: autoflask_sampleapp:app
   :endpoints: user, post
   :undoc-static:
```

```rst
.. autoflask:: autoflask_methodview:app
   :undoc-static:
```

```rst
.. autoflask:: autoflask_methodview:app
   :groupby: view
   :undoc-static:
```

```rst
.. autoflask:: autoflask_alternative_lang:app
   :undoc-static:
```

--------------------------------

### Configure Sphinx Extensions

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Add the autohttp.flask module to the extensions list in your conf.py file.

```python
extensions = ['sphinxcontrib.autohttp.flask']
```

--------------------------------

### Autoflask Directive Usage

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generate API documentation from Flask applications by pointing to the app instance.

```rst
.. autoflask:: myapp:app
   :undoc-static:

.. autoflask:: myapp:create_app(config='production')
   :endpoints: user, post, comment
   :undoc-endpoints: admin, internal_debug
   :order: path

.. autoflask:: myapp:app
   :blueprints: api, public
   :undoc-blueprints: admin
   :modules: myapp.views.public
   :groupby: view
   :include-empty-docstring:
```

```python
# myapp.py - Flask application with documented routes
from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    """Home page.

    .. :quickref: Home; The Home page

    Returns the application home page.
    """
    return 'home'

@app.route('/<user>')
def user(user):
    """User profile page.

    .. :quickref: User; Get Profile Page

    :param user: user login name
    :status 200: when user exists
    :status 404: when user doesn't exist
    """
    return 'hi, ' + user

@app.route('/<user>/posts/<int:post_id>')
def post(user, post_id):
    """User's post.

    :param user: user login name
    :param post_id: post unique id
    :status 200: when user and post exists
    :status 404: when user or post doesn't exist
    """
    return f'{post_id} by {user}'
```

--------------------------------

### Document Bottle Application with autobottle

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use the .. autobottle:: directive to generate HTTP API references from a Bottle application. Specify the application import name, optionally with factory function details.

```rst
.. autobottle:: autobottle_sampleapp:app
```

```rst
.. autobottle:: your.webapplication.module:app
```

```rst
.. autobottle:: your.webapplication.module:create_app(config='default.cfg')
```

--------------------------------

### HTTP Method Directives

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Directives for documenting HTTP methods and their associated details.

```APIDOC
## HTTP Method Directives

### Description
Directives for documenting HTTP methods and their associated details.

### Example

.. sourcecode:: rst

   .. http:post:: /posts/(int:post_id)

      Replies a comment to the post.

      :param post_id: post's unique id
      :type post_id: int
      :form email: author email address
      :form body: comment body
      :reqheader Accept: the response content type depends on
                         :mailheader:`Accept` header
      :reqheader Authorization: optional OAuth token to authenticate
      :resheader Content-Type: this depends on :mailheader:`Accept`
                               header of request
      :status 302: and then redirects to :http:get:`/posts/(int:post_id)`
      :status 400: when form parameters are missing

   .. http:get:: /posts/(int:post_id)

      Fetches the post

      (...)

### Roles

- ``http:options``
- ``http:head``
- ``http:post``
- ``http:get``
- ``http:put``
- ``http:patch``
- ``http:delete``
- ``http:trace``
- ``http:copy``
- ``http:any``
```

--------------------------------

### Bump Version with uv

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/RELEASE.md

After confirming the dry run, execute the uv bump command without the --dry-run flag to update the project's version. Replace <args> with the appropriate versioning arguments.

```shell
uv bump <args>
```

--------------------------------

### Reference an HTTP Method

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use the http:method role to create a hyperlink to a web reference for an HTTP verb.

```rst
It accepts :http:method:`post` only.
```

--------------------------------

### Configure Sphinx for Bottle AutoHTTP

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Add 'sphinxcontrib.autohttp.bottle' to your Sphinx configuration's extensions list in conf.py to enable Bottle API reference generation.

```python
extensions = ['sphinxcontrib.autohttp.bottle']
```

--------------------------------

### Bottle API Reference Generation

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

This section describes the sphinxcontrib.autohttp.bottle extension for generating RESTful HTTP API reference documentation from Bottle applications.

```APIDOC
## :mod:`sphinxcontrib.autohttp.bottle`

### Description
Generates RESTful HTTP API reference documentation from a Bottle application's routing table.

### Method
N/A (Extension)

### Endpoint
N/A (Extension)

### Parameters
N/A (Extension)

### Request Example
N/A (Extension)

### Response
N/A (Generates documentation within Sphinx)
```

--------------------------------

### Add Quick Reference Annotation to Flask Route Docstring

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

When using the quick reference feature, add an rst comment in the format '.. :quickref: [<resource>;] <short description>' within the docstring of your Flask route functions. The '<resource>' is optional and used for grouping, while '<short description>' provides a brief explanation.

```python
@app.route('/<user>')
def user(user):
    """User profile page.

    .. :quickref: User; Get Profile Page

    my docco here
    """
    return 'hi, ' + user
```

--------------------------------

### Autoflask Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generates API documentation from a Flask application's routing table.

```APIDOC
## Autoflask Directive - Automatic Flask API Documentation

Automatically generates API documentation from a Flask application's routing table.

.. autoflask:: myapp:app
   :undoc-static:

.. autoflask:: myapp:create_app(config='production')
   :endpoints: user, post, comment
   :undoc-endpoints: admin, internal_debug
   :order: path

.. autoflask:: myapp:app
   :blueprints: api, public
   :undoc-blueprints: admin
   :modules: myapp.views.public
   :groupby: view
   :include-empty-docstring:
```

```python
# myapp.py - Flask application with documented routes
from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    """Home page.

    .. :quickref: Home; The Home page

    Returns the application home page.
    """
    return 'home'

@app.route('/<user>')
def user(user):
    """User profile page.

    :param user: user login name
    :status 200: when user exists
    :status 404: when user doesn't exist
    """
    return 'hi, ' + user

@app.route('/<user>/posts/<int:post_id>')
def post(user, post_id):
    """User's post.

    :param user: user login name
    :param post_id: post unique id
    :status 200: when user and post exists
    :status 404: when user or post doesn't exist
    """
    return f'{post_id} by {user}'
```

--------------------------------

### Reference API Directives and Methods

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Roles used to link to existing HTTP directives or specific HTTP methods.

```rst
:http:patch:`/users/(int:user_id)/posts/(tag)`

:http:options:`/users/(int:user_id)/posts/(tag)`

:http:get:`/users/(int:user_id)/posts/(tag)`

:http:head:`/users/(int:user_id)/posts/(tag)`

:http:post:`/users/(int:user_id)/posts/(tag)`

:http:put:`/users/(int:user_id)/posts/(tag)`

:http:delete:`/users/(int:user_id)/posts/(tag)`

:http:trace:`/users/(int:user_id)/posts/(tag)`

:http:connect:`/users/(int:user_id)/posts/(tag)`
```

```rst
:http:method:`patch`

:http:method:`options`

:http:method:`get`

:http:method:`head`

:http:method:`post`

:http:method:`put`

:http:method:`delete`

:http:method:`trace`

:http:method:`connect`
```

--------------------------------

### Add sphinxcontrib.httpdomain to Sphinx Extensions

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

To enable the httpdomain extension, add 'sphinxcontrib.httpdomain' to the extensions list in your Sphinx configuration file (conf.py).

```python
extensions = ['sphinxcontrib.httpdomain']
```

--------------------------------

### Document Resource Fields

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Directives for documenting query parameters, headers, and JSON request/response bodies.

```rst
.. http:get:: /foo

   :query resource: description for ``resource``
   :statuscode 200: description for 200
   :statuscode 404: description for 404
```

```rst
.. http:get:: /short-syntax

   :<header Accept: :mimetype:`application/json`
   :<json string foo: Foo key value
   :<json number bar: Bar key value
   :>header Content-Type: :mimetype:`application/json`
   :>jsonarr string baz: Some baz field
   :code 200: Success
```

--------------------------------

### Autotornado Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generates API documentation from a Tornado application's routing table.

```APIDOC
## Autotornado Directive - Automatic Tornado API Documentation

Automatically generates API documentation from a Tornado application.

.. autotornado:: myapp:app

.. autotornado:: myapp:app
   :endpoints: MainHandler.get, UserHandler.get, UserHandler.post
   :undoc-endpoints: AdminHandler.get
   :include-empty-docstring:
```

--------------------------------

### PUT /baz Endpoint

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Documentation for the PUT /baz endpoint, including a synopsis.

```APIDOC
## PUT /baz

### Description
This endpoint performs a special operation.

### Method
PUT

### Endpoint
/baz

### Options
- **synopsis**: Something special
```

--------------------------------

### Specify Flask Application Import Path

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Provide the module path and application variable, or a factory function call, to the autoflask directive.

```rst
your.webapplication.module:app
```

```rst
your.webapplication.module:create_app(config='default.cfg')
```

--------------------------------

### Define HTTP Method Directives

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

Directives for documenting various HTTP methods for a specific API path.

```rst
.. http:patch:: /users/(int:user_id)/posts/(tag)
.. http:options:: /users/(int:user_id)/posts/(tag)
.. http:get:: /users/(int:user_id)/posts/(tag)
.. http:head:: /users/(int:user_id)/posts/(tag)
.. http:post:: /users/(int:user_id)/posts/(tag)
.. http:put:: /users/(int:user_id)/posts/(tag)
.. http:delete:: /users/(int:user_id)/posts/(tag)
.. http:trace:: /users/(int:user_id)/posts/(tag)
.. http:connect:: /users/(int:user_id)/posts/(tag)
.. http:copy:: /users/(int:user_id)/posts/(tag)
```

--------------------------------

### Document Tornado Application with autotornado

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use the .. autotornado:: directive to generate HTTP API references from a Tornado application. Specify the application import name.

```rst
.. autotornado:: autotornado_sampleapp:app
```

```rst
.. autotornado:: your.webapplication.module:app
```

--------------------------------

### Configure Sphinx for Tornado AutoHTTP

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Add 'sphinxcontrib.autohttp.tornado' to your Sphinx configuration's extensions list in conf.py to enable Tornado API reference generation.

```python
extensions = ['sphinxcontrib.autohttp.tornado']
```

--------------------------------

### Autotornado Directive Usage

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Automatically generate API documentation from Tornado applications.

```rst
.. autotornado:: myapp:app

.. autotornado:: myapp:app
   :endpoints: MainHandler.get, UserHandler.get, UserHandler.post
   :undoc-endpoints: AdminHandler.get
   :include-empty-docstring:
```

--------------------------------

### HTTP Directives

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/test/index.rst

The httpdomain extension provides directives for documenting various HTTP methods and endpoints.

```APIDOC
## HTTP Directives

### Description
Directives for documenting HTTP methods and endpoints.

### Methods and Endpoints

- **PATCH** `/users/(int:user_id)/posts/(tag)`
- **OPTIONS** `/users/(int:user_id)/posts/(tag)`
- **GET** `/users/(int:user_id)/posts/(tag)`
- **HEAD** `/users/(int:user_id)/posts/(tag)`
- **POST** `/users/(int:user_id)/posts/(tag)`
- **PUT** `/users/(int:user_id)/posts/(tag)`
- **DELETE** `/users/(int:user_id)/posts/(tag)`
- **TRACE** `/users/(int:user_id)/posts/(tag)`
- **CONNECT** `/users/(int:user_id)/posts/(tag)`
- **COPY** `/users/(int:user_id)/posts/(tag)`
```

--------------------------------

### autoflask Directive

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Documentation for the `autoflask` directive, used to generate API reference documentation from Flask applications.

```APIDOC
## .. autoflask:: directive

### Description

Generates HTTP API references from a Flask application's routing table.

### Usage

.. autoflask:: module:app
   :undoc-static:

   The directive takes an import name (e.g., `your.webapplication.module:app`) where the colon separates the module path and the application variable. It can also handle factory functions like `your.webapplication.module:create_app(config='default.cfg')`.

### Options

- ``endpoints``: Specify which endpoints to document. If omitted or empty, all endpoints are documented.
  Example: `:endpoints: user, post, friends`

- ``undoc-endpoints``: Exclude specified endpoints from the generated references.
  Example: `:undoc-endpoints: admin, admin_login`

- ``undoc-static``: Excludes static endpoints from generated references.

### Version Added

- 1.1
```

--------------------------------

### Reference HTTP Endpoints and Concepts

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Use cross-reference roles to link to documented endpoints, methods, status codes, and headers.

```rst
See :http:get:`/users/(int:user_id)/posts/(tag)` for retrieving user posts.

After creation, you will be redirected to :http:get:`/posts/(int:post_id)`.

This endpoint uses :http:method:`POST` for data submission.

Returns :http:statuscode:`404` when the resource is not found.
Returns :http:statuscode:`200 OK` on success.

The :http:header:`Content-Type` header must be set to :mimetype:`application/json`.
```

--------------------------------

### HTTP POST Directive

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Documents a POST endpoint with form parameters and JSON request/response bodies.

```APIDOC
## POST /posts/(int:post_id)/comments

### Description
Adds a comment to the specified post.

### Method
POST

### Endpoint
/posts/(int:post_id)/comments

#### Parameters
- **post_id** (int) - Required - post's unique id

#### Request Body
- **author** (string) - Required - comment author username
- **body** (string) - Required - comment text content

#### Request Headers
- **Host** (string) - Required - example.com
- **Content-Type** (string) - Required - application/json

#### Response Headers
- **Content-Type** (string) - Description: application/json

#### Success Response (201)
- **comment_id** (int) - Description: created comment's unique identifier
- **created_at** (string) - Description: ISO 8601 timestamp of creation

### Request Example
```http
POST /posts/12345/comments HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "author": "john_doe",
  "body": "Great post!"
}
```

### Response Example
```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "comment_id": 98765,
  "created_at": "2024-01-15T10:30:00Z"
}
```

#### Status Codes
- **201** - comment created successfully
- **400** - invalid request body
- **404** - post not found
```

--------------------------------

### Document HTTP PUT and DELETE Endpoints

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Use the http:put and http:delete directives to document update and deletion operations.

```rst
.. http:put:: /users/(int:user_id)

   Updates the user profile.

   :<json string email: new email address
   :<json string name: new display name
   :>json boolean success: operation result
   :status 200: user updated successfully
   :status 400: validation error
   :status 404: user not found

.. http:delete:: /users/(int:user_id)

   Deletes a user account permanently.

   :param user_id: user's unique identifier
   :reqheader Authorization: Bearer token required
   :status 204: user deleted successfully
   :status 401: unauthorized
   :status 404: user not found
```

--------------------------------

### Specify Endpoints for Bottle Documentation

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use the :endpoints: option with the .. autobottle:: directive to document specific view functions. Omitting this option documents all endpoints.

```rst
.. autobottle:: yourwebapp:app
   :endpoints: user, post, friends
```

```rst
.. autobottle:: yourwebapp:app
   :endpoints:
```

--------------------------------

### Configure HTTP Endpoint Directives

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Use these directives to control endpoint visibility, deprecation status, and table of contents inclusion in the generated documentation.

```rst
.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by tag for user

   Adds a short description visible in the HTTP routing table.

.. http:get:: /v1/users/(int:user_id)/tagged_posts
   :deprecated:

   This endpoint is deprecated. Use ``/users/(int:user_id)/posts/(tag)`` instead.

.. http:get:: /internal/debug
   :noindex:

   This endpoint is excluded from the HTTP routing table.

.. http:get:: /api/items
   :addtoc:

   This endpoint appears in the page-level table of contents.
```

--------------------------------

### Document JSON Request and Response Fields

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Annotate JSON request bodies and response structures using specific field documentation directives.

```rst
.. http:post:: /api/orders

   Creates a new order.

   :<json string customer_id: unique customer identifier
   :<json array items: list of order items
   :<json boolean express: request express shipping
   :<json float discount: discount percentage (0-100)

   :>json string order_id: created order identifier
   :>json string status: order status ("pending", "confirmed")
   :>json float total: total order amount

.. http:get:: /api/orders

   Returns a list of orders.

   :>jsonarr string order_id: order identifier
   :>jsonarr string status: order status
   :>jsonarr float total: total order total
   :>jsonarr string created_at: creation timestamp
```

--------------------------------

### Define JSON request parameters

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use these directives to document fields within a JSON request body.

```rst
:jsonparam string title: the post title
:jsonparam string body: the post body
:jsonparam boolean sticky: whether it's sticky or not
```

```rst
:<json string title: the post title
:<json string body: the post body
:<json boolean sticky: whether it's sticky or not
```

--------------------------------

### Define JSON response parameters

Source: https://github.com/sphinx-contrib/httpdomain/blob/main/docs/index.rst

Use these directives to document fields within a JSON response body.

```rst
:>json boolean ok: Operation status
```

```rst
:>json boolean status: Operation status
```

--------------------------------

### Directive Options

Source: https://context7.com/sphinx-contrib/httpdomain/llms.txt

Control how endpoints appear in the routing table and documentation structure using options like noindex, deprecated, synopsis, and addtoc.

```APIDOC
## Directive Options (noindex, deprecated, synopsis, addtoc)

Control how endpoints appear in the routing table and documentation structure.

.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by tag for user

   Adds a short description visible in the HTTP routing table.

.. http:get:: /v1/users/(int:user_id)/tagged_posts
   :deprecated:

   This endpoint is deprecated. Use ``/users/(int:user_id)/posts/(tag)`` instead.

.. http:get:: /internal/debug
   :noindex:

   This endpoint is excluded from the HTTP routing table.

.. http:get:: /api/items
   :addtoc:

   This endpoint appears in the page-level table of contents.
```
Tokens:
Raw