.. module:: sphinxcontrib.httpdomain

:mod:`sphinxcontrib.httpdomain` --- Sphinx domains for HTTP and WebSocket APIs
==============================================================================

.. image:: https://img.shields.io/pypi/v/sphinxcontrib-httpdomain
    :target: https://pypi.org/project/sphinxcontrib-httpdomain/
    :alt: Latest PyPI version

.. image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-httpdomain
    :target: https://pypi.org/project/sphinxcontrib-httpdomain/
    :alt: Supported Python versions

.. image:: https://app.readthedocs.org/projects/sphinxcontrib-httpdomain/badge/
    :target: https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/
    :alt: Documentation status

.. image:: https://github.com/sphinx-contrib/httpdomain/actions/workflows/tests.yml/badge.svg?branch=main
    :alt: Build status
    :target: https://github.com/sphinx-contrib/httpdomain/actions/workflows/tests.yml

.. image:: https://img.shields.io/pypi/dm/sphinxcontrib-httpdomain
    :alt: PyPI monthly downloads

.. image:: https://img.shields.io/github/sponsors/stevepiercy
    :target: https://github.com/sponsors/stevepiercy
    :alt: GitHub Sponsors

This contrib extension, :mod:`sphinxcontrib.httpdomain`, provides Sphinx
domains for describing HTTP APIs and WebSocket connections.

.. seealso::

   We might support reflection for web framework your webapp depends on.
   See the following :mod:`sphinxcontrib.autohttp` modules:

   Module :mod:`sphinxcontrib.autohttp.flask`
      Reflection for Flask_ webapps.

   Module :mod:`sphinxcontrib.autohttp.flaskqref`
      Quick reference rendering with :mod:`sphinxcontrib.autohttp.flask`

   Module :mod:`sphinxcontrib.autohttp.bottle`
      Reflection for Bottle_ webapps.

   Module :mod:`sphinxcontrib.autohttp.tornado`
      Reflection for Tornado_ webapps.


In order to use it, add :mod:`sphinxcontrib.httpdomain` into
:data:`extensions` list of your Sphinx configuration file (:file:`conf.py`)::

    extensions = ['sphinxcontrib.httpdomain']


Additional Configuration
------------------------

``http_headers_ignore_prefixes``
   List of HTTP header prefixes which should be ignored in strict mode::

       http_headers_ignore_prefixes = ['X-']

   .. versionadded:: 1.4.0

   .. deprecated:: 1.5.0
        strict mode no longer warns on non-standard header prefixes.


``http_index_ignore_prefixes``
   Strips the leading segments from the endpoint paths by given list
   of prefixes::

       http_index_ignore_prefixes = ['/internal', '/_proxy']

   .. versionadded:: 1.3.0

``http_index_shortname``
   Short name of the index which will appear on every page::

       http_index_shortname = 'api'

   .. versionadded:: 1.3.0

``http_index_localname``
   Full index name which is used on index page::

       http_index_localname = "My Project HTTP API"

   .. versionadded:: 1.3.0

``http_strict_mode``
   When ``True`` (default) emits build errors when status codes, methods and
   headers are looks non-standard::

       http_strict_mode = True

   .. versionadded:: 1.4.0


Basic usage
-----------

There are several provided :ref:`directives <directives>` that describe
HTTP resources.

.. sourcecode:: 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

will be rendered as:

    .. 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

Of course, :ref:`roles <roles>` that refer the directives as well.
For example:

.. sourcecode:: rst

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

will render like:

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

If you want to reference the generated routing table, you can use:

.. sourcecode:: rst

   :ref:`routingtable`

.. versionadded:: 1.8.0


.. _directives:
.. _http-directives:

HTTP directives
---------------

.. rst:directive:: .. http:options:: path

   Describes a HTTP resource's :http:method:`OPTIONS` method.
   It can also be referred by :rst:role:`http:options` role.

.. rst:directive:: .. http:head:: path

   Describes a HTTP resource's :http:method:`HEAD` method.
   It can also be referred by :rst:role:`http:head` role.

.. rst:directive:: .. http:post:: path

   Describes a HTTP resource's :http:method:`POST` method.
   It can also be referred by :rst:role:`http:post` role.

.. rst:directive:: .. http:get:: path

   Describes a HTTP resource's :http:method:`GET` method.
   It can also be referred by :rst:role:`http:get` role.

.. rst:directive:: .. http:put:: path

   Describes a HTTP resource's :http:method:`PUT` method.
   It can also be referred by :rst:role:`http:put` role.

.. rst:directive:: .. http:patch:: path

   Describes a HTTP resource's :http:method:`PATCH` method.
   It can also be referred by :rst:role:`http:patch` role.

.. rst:directive:: .. http:delete:: path

   Describes a HTTP resource's :http:method:`DELETE` method.
   It can also be referred by :rst:role:`http:delete` role.

.. rst:directive:: .. http:trace:: path

   Describes a HTTP resource's :http:method:`TRACE` method.
   It can also be referred by :rst:role:`http:trace` role.

.. rst:directive:: .. http:copy:: path

   Describes a HTTP resource's :http:method:`COPY` method.
   It can also be referred by :rst:role:`http:copy` role.

   .. versionadded:: 1.3.0

.. rst:directive:: .. http:any:: path

   Describes a HTTP resource's which accepts requests with
   :http:method:`ANY` method. Useful for cases when requested resource
   proxying the request to some other location keeping original request
   context. It can also be referred by :rst:role:`http:any` role.

   .. versionadded:: 1.3.0


.. _http-options:

HTTP options
````````````

.. versionadded:: 1.3.0

Additionally, you may specify custom options to the directives:

``noindex``
   Excludes specific directive from HTTP routing table.

   .. sourcecode:: rst

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

``deprecated``
   Marks the method as deprecated in HTTP routing table.

   .. sourcecode:: rst

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

``synopsis``
   Adds short description for HTTP routing table.

   .. sourcecode:: rst

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

``addtoc``
   Adds HTTP API endpoint elements to the page-level table of contents.

   .. sourcecode:: rst

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

   .. versionadded:: 2.0.0

.. _resource-fields:

Resource Fields
---------------

Inside HTTP resource description directives such as :rst:dir:`get`, reStructuredText :doc:`field lists <sphinx:usage/restructuredtext/field-lists>` for the following fields are recognized and nicely formatted.

``param``, ``parameter``, ``arg``, ``argument``
   Description of URL parameter.

   Example:

   ..  sourcecode:: rst

       ..  http:post:: /users/(int:user_id)/add/

           :param title: the post title
           :parameter body: the post body
           :arg sticky: whether it's sticky or not
           :argument publish: publication date

   Rendering:

   ..  http:post:: /users/(int:user_id)/add/

       :param title: the post title
       :parameter body: the post body
       :arg sticky: whether it's sticky or not
       :argument publish: publication date

``queryparameter``, ``queryparam``, ``qparam``, ``query``
   Description of parameter passed by request query string.

   It can be typed.
   Although all the query parameters will be string types, it's useful if there are conventions for it.

   .. versionchanged:: 1.1.9

      It can be typed, for example:

      ..  sourcecode:: rst

          ..  http:get:: /users/(int:user_id)/posts/view

              :param string title: the post title
              :parameter string body: the post body
              :arg boolean sticky: whether it's sticky or not
              :argument date publish: publication date

      Rendering:

      ..  http:get:: /users/(int:user_id)/posts/view

          :param string title: the post title
          :parameter string body: the post body
          :arg boolean sticky: whether it's sticky or not
          :argument date publish: publication date

``formparameter``, ``formparam``, ``fparam``, ``form``
   Description of parameter passed by request content body, encoded in
   :mimetype:`application/x-www-form-urlencoded` or
   :mimetype:`multipart/form-data`.

``jsonparameter``, ``jsonparam``, ``json``
   Description of a parameter passed by request content body, encoded in
   :mimetype:`application/json`.

   .. deprecated:: 1.3.0

      Use ``reqjsonobj``/``reqjson``/``>jsonobj``/``>json`` and
      ``reqjsonarr``/``>jsonarr`` instead.

   .. versionadded:: 1.1.8

   .. versionchanged:: 1.1.9

      It can be typed, for example:

      .. sourcecode:: rst

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

``reqjsonobj``, ``reqjson``, ``>jsonobj``, ``>json``
   Description of a single field of a JSON object passed in the request body, and encoded in :mimetype:`application/json`.
   The key difference from ``json`` is that the request is explicitly defined in the described object.

   Using the following JSON object, it can be typed as shown in the subsequent example.

   ..  code-block:: json

       {
         "user_id": 1,
         "post_id": 2
       }

   ..  code-block:: rst

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

           :reqjson integer user_id: The user ID.
           :>json integer post_id: The post ID.

   Rendering:

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

       :reqjson integer user_id: The user ID.
       :>json integer post_id: The post ID.

   Additionally, it can be typed as a JSON object.

   ..  code-block:: rst

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

           :reqjson reqjsonobj user_id: The user ID.
           :>json >jsonobj post_id: The post ID.

   Rendering:

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

       :reqjson reqjsonobj user_id: The user ID.
       :>json >jsonobj post_id: The post ID.

   .. versionadded:: 1.3.0

``resjsonobj``, ``resjson``, ``<jsonobj``, ``<json``
   Description of a single field of a JSON object returned in the response body, and encoded in :mimetype:`application/json`.
   The key difference from ``json`` is that the response is explicitly defined in the described object.

   ..  code-block:: rst

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

           :resjson boolean ok: Operation status.
           :<json integer error: Error code.

   Rendering:

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

       :resjson boolean ok: Operation status.
       :<json integer error: Error code.

   Additionally, it can be typed as a JSON object.

   ..  code-block:: rst

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

           :resjson resjsonobj ok: Operation status.
           :<json <jsonobj error: Error code.

   Rendering:

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

       :resjson resjsonobj ok: Operation status.
       :<json <jsonobj error: Error code.

   .. versionadded:: 1.3.0

``reqjsonarr``, ``>jsonarr``,
``resjsonarr``, ``<jsonarr``

   Similar to ``>json`` and ``<json``, respectively, but used for describing
   object schema inside of the returned array.

   Let's say the response contains the following data:

   .. sourcecode:: json

      [
        {
          "id": "foo",
          "ok": true
        },
        {
          "id": "bar",
          "error": "forbidden",
          "reason": "sorry"
        }
      ]

   Then we can describe it in the following way:

   .. sourcecode:: rst

      :<jsonarr boolean ok: Operation status. Not present in case of error
      :<jsonarr string id: Object ID
      :<jsonarr string error: Error type
      :<jsonarr string reason: Error reason

   .. versionadded:: 1.3.0

``requestheader``, ``reqheader``, ``>header``
   Description of request header field.

   .. versionadded:: 1.1.9

``responseheader``, ``resheader``, ``<header``
   Description of response header field.

   .. versionadded:: 1.1.9

``statuscode``, ``status``, ``code``
   Description of response status code.

For 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

      (...)

It will render like this:

    .. 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:

Roles
-----

.. rst:role:: http:options

   Refers to the :rst:dir:`http:options` directive.

.. rst:role:: http:head

   Refers to the :rst:dir:`http:head` directive.

.. rst:role:: http:post

   Refers to the :rst:dir:`http:post` directive.

.. rst:role:: http:get

   Refers to the :rst:dir:`http:get` directive.

.. rst:role:: http:put

   Refers to the :rst:dir:`http:put` directive.

.. rst:role:: http:patch

   Refers to the :rst:dir:`http:patch` directive.

.. rst:role:: http:delete

   Refers to the :rst:dir:`http:delete` directive.

.. rst:role:: http:trace

   Refers to the :rst:dir:`http:trace` directive.

.. rst:role:: http:copy

   Refers to the :rst:dir:`http:copy` directive.

.. rst:role:: http:any

   Refers to the :rst:dir:`http:any` directive.

.. rst:role:: http:statuscode

   A reference to a HTTP status code. The text "`code` `Status Name`" is
   generated; in the HTML output, this text is a hyperlink to a web reference
   of the specified status code.

   For example:

   .. sourcecode:: rst

      - :http:statuscode:`404`
      - :http:statuscode:`200 OK`

   will be rendered as:

       - :http:statuscode:`404`
       - :http:statuscode:`200 OK`

   .. versionchanged:: 1.3.0
      It becomes to provide references to specification sections.

.. rst:role:: http:method

   A reference to a HTTP method (also known as *verb*). In the HTML output,
   this text is a hyperlink to a web reference of the specified HTTP method.

   For example:

   .. sourcecode:: rst

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

   It will render like this:

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

.. rst:role:: mimetype

   Exactly it doesn't belong to HTTP domain, but standard domain. It refers
   to the MIME type like :mimetype:`text/html`.

.. rst:role:: mailheader

   .. deprecated:: 1.3.0
      Use :rst:role:`http:header` instead.

.. rst:role:: http:header

   Similar to :rst:role:`mimetype` role, it doesn't belong to HTTP domain,
   but standard domain. It refers to the HTTP request/response header field
   like :http:header:`Content-Type`.

   If the HTTP header is known, the text is a hyperlink to a web reference of
   the specified header.

   Known HTTP headers:

   - :http:header:`Accept`
   - :http:header:`Accept-Charset`
   - :http:header:`Accept-Encoding`
   - :http:header:`Accept-Language`
   - :http:header:`Accept-Ranges`
   - :http:header:`Age`
   - :http:header:`Allow`
   - :http:header:`Authorization`
   - :http:header:`Cache-Control`
   - :http:header:`Connection`
   - :http:header:`Content-Encoding`
   - :http:header:`Content-Language`
   - :http:header:`Content-Length`
   - :http:header:`Content-Location`
   - :http:header:`Content-MD5`
   - :http:header:`Content-Range`
   - :http:header:`Content-Type`
   - :http:header:`Cookie`
   - :http:header:`Date`
   - :http:header:`Destination`
   - :http:header:`ETag`
   - :http:header:`Expect`
   - :http:header:`Expires`
   - :http:header:`From`
   - :http:header:`Host`
   - :http:header:`If-Match`
   - :http:header:`If-Modified-Since`
   - :http:header:`If-None-Match`
   - :http:header:`If-Range`
   - :http:header:`If-Unmodified-Since`
   - :http:header:`Last-Modified`
   - :http:header:`Last-Event-ID`
   - :http:header:`Link`
   - :http:header:`Location`
   - :http:header:`Max-Forwards`
   - :http:header:`Pragma`
   - :http:header:`Proxy-Authenticate`
   - :http:header:`Proxy-Authorization`
   - :http:header:`Range`
   - :http:header:`Referer`
   - :http:header:`Retry-After`
   - :http:header:`Server`
   - :http:header:`Set-Cookie`
   - :http:header:`TE`
   - :http:header:`Trailer`
   - :http:header:`Transfer-Encoding`
   - :http:header:`Upgrade`
   - :http:header:`User-Agent`
   - :http:header:`Vary`
   - :http:header:`Via`
   - :http:header:`WWW-Authenticate`
   - :http:header:`Warning`

   .. versionadded:: 1.3.0

   .. versionchanged:: 1.5.0

        No longer emits warnings for unrecognized headers

.. module:: sphinxcontrib.autohttp.flask

:mod:`sphinxcontrib.autohttp.flask` --- Exporting API reference from Flask app
------------------------------------------------------------------------------

.. versionadded:: 1.1

It generates RESTful HTTP API reference documentation from a Flask_
application's routing table, similar to :mod:`sphinx.ext.autodoc`.

In order to use it, add :mod:`sphinxcontrib.autohttp.flask` into
:data:`extensions` list of your Sphinx configuration (:file:`conf.py`) file::

    extensions = ['sphinxcontrib.autohttp.flask']

For example:

.. sourcecode:: rst

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

will be rendered as:

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

.. rst:directive:: .. autoflask:: module:app

   .. versionadded:: 1.1

   Generates HTTP API references from a Flask application. It takes an
   import name, like::

       your.webapplication.module:app

   Colon character (``:``) separates module path and application variable.
   Latter part can be more complex::

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

   It's useful when a Flask application is created from the factory function
   (:func:`create_app`, in the above example).

   It takes several flag options as well.

   ``endpoints``
      Endpoints to generate a reference.

      .. sourcecode:: rst

         .. autoflask:: yourwebapp:app
            :endpoints: user, post, friends

      will document :func:`user`, :func:`post`, and :func:`friends`
      view functions, and

      .. sourcecode:: rst

         .. autoflask:: yourwebapp:app
            :endpoints:

      will document all endpoints in the flask app.

      For compatibility, omitting this option will produce the same effect
      like above.

      .. versionadded:: 1.1.8

   ``undoc-endpoints``
      Excludes specified endpoints from generated references.

      For example:

      .. sourcecode:: rst

         .. autoflask:: yourwebapp:app
            :undoc-endpoints: admin, admin_login

      will exclude :func:`admin`, :func:`admin_login` view functions.

      .. note::

         It is worth noting that the names of endpoints that are applied to
         blueprints are prefixed with the blueprint's name (e.g.
         blueprint.endpoint).

      .. note::

         While the `undoc-members`_ flag of :mod:`sphinx.ext.autodoc` extension
         includes members without docstrings, ``undoc-endpoints`` option has
         nothing to do with docstrings. It just excludes specified endpoints.

         .. _undoc-members: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members

   ``blueprints``
      Only include specified blueprints in generated references.

      .. versionadded:: 1.1.9

   ``undoc-blueprints``
      Excludes specified blueprints from generated references.

      .. versionadded:: 1.1.8

   ``modules``
      Only include specified view modules in generated references.

      For example:

      .. sourcecode:: rst

         .. autoflask:: yourwebapp:app
            :modules: yourwebapp.views.admin

      will include only views in ``yourwebapp.views.admin`` module

      .. versionadded:: 1.5.0

   ``undoc-modules``
      Excludes specified view modules from generated references.

      .. versionadded:: 1.5.0

   ``undoc-static``
      Excludes a view function that serves static files, which is included
      in Flask by default.

   ``order``
      Determines the order in which endpoints are listed. Currently only
      ``path`` is supported.

      For example:

      .. sourcecode:: rst

         .. autoflask:: yourwebapp:app
            :endpoints:
            :order: path

      will document all endpoints in the flask app, ordered by their route
      paths.

      .. versionadded:: 1.5.0

   ``groupby``
      Determines the strategy to group paths. Currently only ``view`` is
      supported. Specified this will group paths by their view functions.

      .. versionadded:: 1.6.0

   ``include-empty-docstring``
      View functions that don't have docstring (:attr:`__doc__`) are excluded
      by default. If this flag option has given, they become included also.

      .. versionadded:: 1.1.2

.. _Flask: https://www.palletsprojects.com/projects/flask/


.. module:: sphinxcontrib.autohttp.flaskqref

:mod:`sphinxcontrib.autohttp.flaskqref` --- Quick API reference for Flask app
------------------------------------------------------------------------------

.. versionadded:: 1.5.0

This generates a quick API reference table for the route documentation
produced by :mod:`sphinxcontrib.autohttp.flask`

To use it, both :mod:`sphinxcontrib.autohttp.flask` and :mod:`sphinxcontrib.autohttp.flaskqref` need to be added into the extensions
of your configuration (:file:`conf.py`) file::

    extensions = ['sphinxcontrib.autohttp.flask',
                  'sphinxcontrib.autohttp.flaskqref']

.. rst:directive:: .. qrefflask:: module:app

   .. versionadded:: 1.5.0

   Generates HTTP API references from a Flask application and places these
   in a list-table with quick reference links. The usage and options are identical
   to that of :mod:`sphinxcontrib.autohttp.flask` with the addition of the
   ``autoquickref`` option.


Basic usage
```````````

You typically would place the quick reference table near the top of your docco
and use *.. autoflask::* further down.

Unless you use the ``autoquickref`` option, routes that are to be included in
the quick reference table require the following rst comment to be added to their
doc string:

.. sourcecode:: rst

    .. :quickref: [<resource>;] <short description>

<resource> is optional, if used a semi-colon separates it from <short description>
The table is grouped and sorted by <resource>.

``<resource>``
   This is the resource name of the operation.  The name maybe the same for a number
   of operations and enables grouping these together.

``<short description>``
   A brief description what the operation does.

If you use the ``autoquickref`` option, all routes must be inside blueprints.
The ``<resource>`` will be set to the blueprint's name, and the ``<short
description>`` will be set to the first line of the docstring.

For example:

.. sourcecode:: python

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

        .. :quickref: User; Get Profile Page

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


The quick reference table is defined as:

.. sourcecode:: rst

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

Using the autoflask_sampleapp with *.. :quickref:* annotations,
this is rendered as:

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


.. module:: sphinxcontrib.autohttp.bottle

:mod:`sphinxcontrib.autohttp.bottle` --- Exporting API reference from Bottle app
--------------------------------------------------------------------------------

It generates RESTful HTTP API reference documentation from a Bottle_
application's routing table, similar to :mod:`sphinx.ext.autodoc`.

In order to use it, add :mod:`sphinxcontrib.autohttp.bottle` into
:data:`extensions` list of your Sphinx configuration (:file:`conf.py`) file::

    extensions = ['sphinxcontrib.autohttp.bottle']

For example:

.. sourcecode:: rst

   .. autobottle:: autobottle_sampleapp:app

will be rendered as:

    .. autobottle:: autobottle_sampleapp:app

.. rst:directive:: .. autobottle:: module:app

   Generates HTTP API references from a Bottle application. It takes an
   import name, like::

       your.webapplication.module:app

   Colon character (``:``) separates module path and application variable.
   Latter part can be more complex::

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

   It's useful when a Bottle application is created from the factory function
   (:func:`create_app`, in the above example).

   It takes several flag options as well.

   ``endpoints``
      Endpoints to generate a reference.

      .. sourcecode:: rst

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

      will document :func:`user`, :func:`post`, and :func:`friends`
      view functions, and

      .. sourcecode:: rst

         .. autobottle:: yourwebapp:app
            :endpoints:

      will document all endpoints in the bottle app.

      For compatibility, omitting this option will produce the same effect
      like above.

   ``undoc-endpoints``
      Excludes specified endpoints from generated references.

      For example:

      .. sourcecode:: rst

         .. autobottle:: yourwebapp:app
            :undoc-endpoints: admin, admin_login

      will exclude :func:`admin`, :func:`admin_login` view functions.

      .. note::

         While the `undoc-members`_ flag of :mod:`sphinx.ext.autodoc` extension
         includes members without docstrings, ``undoc-endpoints`` option has
         nothing to do with docstrings. It just excludes specified endpoints.

         .. _undoc-members: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members

   ``include-empty-docstring``
      View functions that don't have docstring (:attr:`__doc__`) are excluded
      by default. If this flag option has given, they become included also.

.. _Bottle: https://bottlepy.org/docs/stable/

.. module:: sphinxcontrib.autohttp.tornado

:mod:`sphinxcontrib.autohttp.tornado` --- Exporting API reference from Tornado app
----------------------------------------------------------------------------------

It generates RESTful HTTP API reference documentation from a Tornado_
application's routing table, similar to :mod:`sphinx.ext.autodoc`.

In order to use it, add :mod:`sphinxcontrib.autohttp.tornado` into
:data:`extensions` list of your Sphinx configuration (:file:`conf.py`) file::

    extensions = ['sphinxcontrib.autohttp.tornado']

For example:

.. sourcecode:: rst

   .. autotornado:: autotornado_sampleapp:app

will be rendered as:

    .. autotornado:: autotornado_sampleapp:app

.. rst:directive:: .. autotornado:: module:app

   Generates HTTP API references from a Tornado application. It takes an
   import name, like::

       your.webapplication.module:app

   Colon character (``:``) separates module path and application variable.

   It takes several flag options as well.

   ``endpoints``
      Endpoints to generate a reference.

      .. sourcecode:: rst

         .. autotornado:: yourwebapp:app
            :endpoints: User.get, User.post, Friends.get

      will document the :func:`get` and :func:`post` methods of the
      :class:`User` :class:`RequestHandler` and the :func:`get` method
      of the :class:`Friend` :class:`RequestHandler`, while

      .. sourcecode:: rst

         .. autotornado:: yourwebapp:app
            :endpoints:

      will document all endpoints in the tornado app.

      For compatibility, omitting this option will produce the same effect
      like above.

   ``undoc-endpoints``
      Excludes specified endpoints from generated references.

      For example:

      .. sourcecode:: rst

         .. autotornado:: yourwebapp:app
            :undoc-endpoints: admin, admin_login

      will exclude :func:`admin`, :func:`admin_login` view functions.

      .. note::

         While the `undoc-members`_ flag of :mod:`sphinx.ext.autodoc` extension
         includes members without docstrings, ``undoc-endpoints`` option has
         nothing to do with docstrings. It just excludes specified endpoints.

         .. _undoc-members: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members

   ``include-empty-docstring``
      View functions that don't have docstring (:attr:`__doc__`) are excluded
      by default. If this flag option has given, they become included also.

.. _Tornado: https://www.tornadoweb.org/en/stable/


.. _websocket-connections:

WebSocket connections
---------------------

The ``websocket`` domain documents a bidirectional WebSocket connection.  Its
path is the exact leading-slash application path, including any typed
placeholder; put the scheme and host in surrounding prose.  Directions are
always relative to the documented WebSocket server: ``server-message`` entries
are sent by that server, and ``client-message`` entries are received by it.

.. sourcecode:: rst

   .. websocket:connection:: /chat/(str:room)
      :synopsis: Join a chat room.
      :addtoc:

      Clients join a room, then exchange application-defined messages.

      :param string room: room identifier
      :query string token: optional access token
      :server-message joined: confirms that the client joined the room
      :server-message message: delivers a room message
      :client-message send: sends a room message

The directive renders as:

   .. websocket:connection:: /chat/(str:room)
      :synopsis: Join a chat room.
      :addtoc:

      Clients join a room, then exchange application-defined messages.

      :param string room: room identifier
      :query string token: optional access token
      :server-message joined: confirms that the client joined the room
      :server-message message: delivers a room message
      :client-message send: sends a room message

Use the exact same path to create a cross-reference:

.. sourcecode:: rst

   :websocket:connection:`/chat/(str:room)`
   :websocket:connection:`Chat connection </chat/(str:room)>`

You can reference the generated index with
``:ref:`websocket-routingtable```.

.. _websocket-options:

WebSocket options
`````````````````

``deprecated``
   Marks the connection as deprecated in the WebSocket routing table.

``synopsis``
   Adds a short description to the WebSocket routing table.

``addtoc``
   Adds the connection to the page-level table of contents.

``noindex``
   Renders the connection without adding it to the WebSocket routing table or
   object inventory.  A ``noindex`` connection cannot be cross-referenced or
   added to the page-level table of contents.

Only ``param``, ``query``, ``server-message``, and ``client-message`` are
WebSocket fields.  Message names are author-defined identifiers, not schemas
or protocol events.  HTTP handshake fields, ``http:ws`` and ``ws`` aliases,
event aliases, schemas, frames, close codes, subprotocols, framework
discovery, and AsyncAPI are outside this first implementation.


Author and License
------------------

The :mod:`sphinxcontrib.httpdomain` and :mod:`sphinxcontrib.autohttp`,
parts of :mod:`sphinxcontrib`, are written by `Hong Minhee`_
and distributed under BSD license.

The source code is maintained under `the sphinx-contrib project`__
in the `httpdomain`_ repository

.. sourcecode:: console

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

.. _Hong Minhee: https://hongminhee.org/
__ https://github.com/sphinx-contrib
.. _httpdomain: https://github.com/sphinx-contrib/httpdomain


.. include:: ../CHANGELOG.rst