Sphinx

# The JavaScript Domain

Added in version 1.0.

The JavaScript domain (name js) provides the following directives:

.. js:module:: name

  This directive sets the module name for object declarations that follow after. The module name is used in the global module index and in cross references. This directive does not create an object heading like `py:class` would, for example.

  By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the `no-index` option is specified. If this option is specified, the directive will only update the current module name.

  Added in version 1.6.

  Changed in version 5.2: Module directives support body content.

.. js:function:: name(signature)

  Describes a JavaScript function or method. If you want to describe arguments as optional use square brackets as documented for Python signatures.

  You can use fields to give more details about arguments and their expected types, errors which may be thrown by the function, and the value being returned:

      .. js:function:: $.getJSON(href, callback[, errback])

         :param string href: An URI to the location of the resource.
         :param callback: Gets called with the object.
         :param errback:
             Gets called in case the request fails. And a lot of other
             text so we need multiple lines.
         :throws SomeError: For whatever reason in that case.
         :returns: Something.

  This is rendered as:

  $.getJSON(href, callback[, errback])
    Arguments:

      - href (`string()`) – An URI to the location of the resource.

      - callback – Gets called with the object.

      - errback – Gets called in case the request fails. And a lot of other text so we need multiple lines.

    Throws:

      `SomeError()` – For whatever reason in that case.

    Returns:

      Something.

  :single-line-parameter-list: (no value)

    Ensures that the function’s parameters will be emitted on a single logical line, overriding `javascript_maximum_signature_line_length` and `maximum_signature_line_length`.

    Added in version 7.1.

.. js:method:: name(signature)

  This directive is an alias for `js:function`, however it describes a function that is implemented as a method on a class object.

  Added in version 1.6.

  :single-line-parameter-list: (no value)

    Ensures that the function’s parameters will be emitted on a single logical line, overriding `javascript_maximum_signature_line_length` and `maximum_signature_line_length`.

    Added in version 7.1.

.. js:class:: name

  Describes a constructor that creates an object. This is basically like a function but will show up with a class prefix:

      .. js:class:: MyAnimal(name[, age])

         :param string name: The name of the animal
         :param number age: an optional age for the animal

  This is rendered as:

  class MyAnimal(name[, age])
    Arguments:

      - name (`string()`) – The name of the animal

      - age (`number()`) – an optional age for the animal

  :single-line-parameter-list: (no value)

    Ensures that the function’s parameters will be emitted on a single logical line, overriding `javascript_maximum_signature_line_length` and `maximum_signature_line_length`.

    Added in version 7.1.

.. js:data:: name

  Describes a global variable or constant.

.. js:attribute:: object.name

  Describes the attribute name of object.

These roles are provided to refer to the described objects:

:js:mod:
:js:func:
:js:meth:
:js:class:
:js:data:
:js:attr: