Usage¶

Before you can use this extension, you need to install the sphinx-jsondomain Python package and then add the sphinxjsondomain module to extensions list in your Sphinx configuration file (conf.py):

extensions = ['sphinxjsondomain']

Then you can use the json:object directive to document your JSON documents.

ReStructuredText Usage¶

.. json:object:: Object Name¶

Documents the structure of a JSON document using the name Object Name. The description is referenceable using the json:object role. Each property of the JSON document is described using a separate

:property [type] identifier : description: Documents the property named identifier. The property’s type can be specified inline or as a separate :proptype: option. The type is shown in the rendered output and linked if the type is something recognizable. It is also used to generate sample data, if the :showexample: option is included.
:proptype identifier : type: Set’s the type of the property named identifier. This is necessary if you are setting the property type to a hyperlinked value (e.g., json:object role instance).
:showexample:: If this option is specified, then the rendered output will contain a generated example. The example data is generated using the Python fake-factory library. See Recognized Types for more details.
:noindex:: Do not include this object in the general index.
:options identifier : option-list: Options are a comma-separated list of values that are rendered in italics after the property’s description. The extension does not interpret the option values in any way.

Note

The :options: option will be used to in the near future to enable additional functionality such as adding constraints when generating a JSON Schema for types.

:json:object:¶: Links to the named json:object directive.

Recognized Types¶

Types are used for two distinct purposes in this extension. First of all, they are linked to appropriate documentation. Secondly, they are used to generate example snippets if the :showexample: option is included.

uri, url links to the relevant IETF RFC that describes URL: syntax. Examples are generated using faker.providers.internet.
boolean links to the definition for the Python bool type.: Examples are generated using faker.providers.python.
string, str links to the definition for the Python str: type. Examples are generated using faker.providers.python.
integer, int links to the definition for the Python int: type. Examples are generated using faker.providers.python.
float, number links to the definition for the Python float: type. Examples are generated using faker.providers.python.

null links to the definition for the Python None value.

email links to RFC 2822 since it is the formal definition of an: email address. Examples are generated using faker.providers.internet.
iso8601 links to RFC 3339 since it is a good (and freely available): description of the ISO-8601 format. Examples are generated using faker.providers.date_time.
uuid4 links to RFC 4122 since it is the definitive specification: for UUIDv4 values. Examples are generated using faker.providers.misc.
md5 links to RFC 1321. Examples are generated using: faker.providers.misc.
sha1 links to RFC 3174. Examples are generated using: faker.providers.misc.
sha256 links to RFC 6234. Examples are generated using: faker.providers.misc.
user_name links to the defintion for the Python str type.: Examples are generated using faker.providers.internet.

Example Generation¶

As mentioned elsewhere, this extensions uses the fake-factory library to generate sample data. If the “type” of the property is an attribute of a faker.Factory instance, then the method is called to generate the sample value. Otherwise, the extension will handle integer, float, boolean, string, and None values by calling the appropriate faker methods.

The other interesting case is the one of embedded objects. If you set the property type to a json:object reference, then the documented object is included recursively. Let’s look at a simple example.

.. json:object:: Contact
   :showexample:

   :property name preferred_name: contact's preferred name in
      correspondance
   :property address: mailing address of contact
   :proptype address: :json:object:`Address`

.. json:object:: Address
   :showexample:

   :property street_address street: street address for this
      location
   :property city city: city name
   :property state_abbr state: abbreviated state name
   :property postalcode zip: postal code for this address

And this is the rendered version. Pay particular attention to the handling of the address property. The property type is specified using the :proptype: option so that we can use a link to another JSON object (e.g., :json:object`Address` on line 7). The extension recognizes linked objects and embeds an instance of them in the generated example.

Contact¶

Object Properties:
	preferred_name (name) – contact’s preferred name in correspondance address (`Address`) – mailing address of contact

JSON Example

{
    "preferred_name": "Raymond Hurst",
    "address": {
        "zip": "33703",
        "street": "231 Rowland Ford Apt. 381",
        "state": "VA",
        "city": "Henryview"
    }
}

Address¶

Object Properties:
	street (street_address) – street address for this location city (city) – city name state (state_abbr) – abbreviated state name zip (postalcode) – postal code for this address

JSON Example

{
    "zip": "14771",
    "street": "506 Jones Rest Suite 574",
    "state": "VA",
    "city": "Carrhaven"
}

Index Generation¶

json:object directives are added to the general index as children of the JSON Objects entry. You can inhibit this on a directive-by-directive basis by including the :noindex: option.