sphinxcontrib-opendataservices

Open Data Services’ Sphinx directives.

Installation

Add this line to your requirements.txt:

-e git+https://github.com/OpenDataServices/sphinxcontrib-opendataservices.git@23ce17656feaa237584af8822bd57ac39b498f93#egg=sphinxcontrib-opendataservices

Then run pip install -r requirements.txt.

Edit your doc’s conf.py and add sphinxcontrib.opendataservices to the extensions array.

e.g.

extensions = ['sphinxcontrib.opendataservices']

JSON Include Directives

Standard JSON Include

.. jsoninclude::

Include a section of a JSON file, given a jsonpointer.

e.g. using this json file:

Source:

```{eval-rst}
.. jsoninclude:: _static/example.json
    :jsonpointer: /a/0/b
    :expand: e
```

Output:

{
    "c": 1,
    "d": 2,
    "e": [
        {
            "f": 3
        },
        {
            "f": 4
        }
    ],
    "g": 5
}

The expand option is needed to expand a list when the json is folded by javascript. For more info see Javascript below.

exclude option:

Source:

```{eval-rst}
.. jsoninclude:: _static/example.json
    :jsonpointer: /a/0/b
    :exclude: e,g
```

Output:

{
    "c": 1,
    "d": 2
}

include_only option:

Source:

```{eval-rst}
.. jsoninclude:: _static/example.json
    :jsonpointer: /a/0/b
    :include_only: e,g
    :expand: e
```

Output:

{
    "e": [
        {
            "f": 3
        },
        {
            "f": 4
        }
    ],
    "g": 5
}

Javascript

To fold the JSON with javascript, you need to include the following files:

You need to add the files to a _static folder within your docs, and then add the following to _templates/layout.html.

{% extends "!layout.html" %}
{% set css_files = css_files + ["_static/renderjson.css"] %}
{% set script_files = script_files + ["_static/renderjson.js", "_static/json-example-format.js"] %}

The option expand can be used to control which lists are expanded initially. The option title can be used to give the json include a title; only one of consecutive includes will be shown, with a select box to switch:

Source:

```{eval-rst}
.. jsoninclude:: _static/example.json
    :jsonpointer:
    :title: collapsed

.. jsoninclude:: _static/example.json
    :jsonpointer:
    :expand: a,b,e,h
    :title: expanded
```

Output:

{
    "a": [
        {
            "b": {
                "c": 1,
                "d": 2,
                "e": [
                    {
                        "f": 3
                    },
                    {
                        "f": 4
                    }
                ],
                "g": 5
            }
        }
    ],
    "h": [
        {
            "i": 11,
            "j": 12
        },
        {
            "k": 13,
            "l": 14
        }
    ]
}

{
    "a": [
        {
            "b": {
                "c": 1,
                "d": 2,
                "e": [
                    {
                        "f": 3
                    },
                    {
                        "f": 4
                    }
                ],
                "g": 5
            }
        }
    ],
    "h": [
        {
            "i": 11,
            "j": 12
        },
        {
            "k": 13,
            "l": 14
        }
    ]
}

Flat JSON Include

.. jsoninclude-flat::

Include a section of a JSON file, flattened into a table representation, given a jsonpointer.

Examples, using this json file:

Source:

```{eval-rst}
.. jsoninclude-flat:: _static/example.json
    :jsonpointer: /a/0/b
```

Output:

/a/0/b/c

/a/0/b/d

/a/0/b/g

1

2

5

recursive (include nested dicts and lists):

Source:

```{eval-rst}
.. jsoninclude-flat:: _static/example.json
    :jsonpointer: /a/0/b
    :recursive:
```

Output:

/a/0/b/c

/a/0/b/d

/a/0/b/e/0/f

/a/0/b/e/1/f

/a/0/b/g

1

2

3

4

5

List of items directly under the json pointer:

Source:

```{eval-rst}
.. jsoninclude-flat:: _static/example.json
    :jsonpointer: /h
```

Output:

/h/k

/h/l

11

12

13

14

Remove part of the path from the headings uwsing ignore_path:

Source:

```{eval-rst}
.. jsoninclude-flat:: _static/example.json
    :jsonpointer: /a/0/b
    :ignore_path: /a/0/b/
```

Output:

c

d

g

1

2

5

jsoninclude-flat also has the options exclude and include_only, the same as for jsoninclude (see above).

JSON Schema Directives

.. jsonschema::

The core jsonschema directive, mainatined in the sphinxcontrib-jsonschema repository.

The exact output of this is somewhat specific to the OCDS usecases, so we subclass the directive to create alternatives for other data standards, see below.

Source:

```{eval-rst}
.. jsonschema:: _static/example_schema.json
```

Output:

Title

Description

Type

Format

Required
id

string

Required

Identifier

An identifier
foo

integer

Foo bar

Foo bar baz bar baz bar baz bar baz. Bar foo baz foo bar. Baz bar foo bar foo bar foo bar foo.
when

string

date-time

Required

When

When did this thing happen
lorem

string

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur porttitor urna in diam ornare luctus. Donec accumsan sit amet velit id auctor. Sed commodo elit ut tempor suscipit. Fusce volutpat malesuada felis, accumsan molestie nisi aliquet non. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
subthings

array[object]

SubThing

Description of SubThing
subthings/0/id

string

Required

Identifier

An identifier for this subthing
subthings/0/example

string

Example

An example field
.. jsonschema-titles::

Display titles, but not field names.

Currently only used for 360Giving.

Source:

```{eval-rst}
.. jsonschema-titles:: _static/example_schema.json
```

Output:

Title

Description

Type

Required

Identifier

An identifier

string

True

Foo bar

Foo bar baz bar baz bar baz bar baz. Bar foo baz foo bar. Baz bar foo bar foo bar foo bar foo.

integer

False

When

When did this thing happen

date-time

True

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur porttitor urna in diam ornare luctus. Donec accumsan sit amet velit id auctor. Sed commodo elit ut tempor suscipit. Fusce volutpat malesuada felis, accumsan molestie nisi aliquet non. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.

string

False

Source:

```{eval-rst}
.. jsonschema-titles:: _static/example_schema.json
    :child: subthings
```

Output:

Description of SubThing

Title

Description

Type

Required

SubThing:Identifier

An identifier for this subthing

string

True

SubThing:Example

An example field

string

False
.. jsonschema-title-fieldname-map::

Display the mapping between titles and field names.

Currently only used for 360Giving.

Source:

```{eval-rst}
.. jsonschema-title-fieldname-map:: _static/example_schema.json
```

Output:

Title

Name

Type

Identifier

id

string

Foo bar

foo

integer

When

when

date-time

Lorem ipsum

lorem

string

SubThing:Identifier

subthings/0/id

string

SubThing:Example

subthings/0/example

string
.. jsonschema-array::

Handle a jsonschema where the top element is an array. Don’t display titles in the table.

Currently only used for OpenReferral.

Source:

```{eval-rst}
.. jsonschema-array:: _static/example_schema_array.json
```

Output:

Description

Type

Required
id

An identifier

string

True
foo

Foo bar baz bar baz bar baz bar baz. Bar foo baz foo bar. Baz bar foo bar foo bar foo bar foo.

integer

False
when

When did this thing happen

date-time

True
lorem

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur porttitor urna in diam ornare luctus. Donec accumsan sit amet velit id auctor. Sed commodo elit ut tempor suscipit. Fusce volutpat malesuada felis, accumsan molestie nisi aliquet non. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.

string

False
subthings/0/id

An identifier for this subthing

string

True
subthings/0/example

An example field

string

False

CSS

To display the tables better, add this css to your site: jsonschema.css. You need to add the file to a _static folder within your docs, and then add the following to _templates/layout.html.

{% extends "!layout.html" %}
{% set css_files = css_files + ["_static/jsonschema.css"] %}

Misc Directives

.. csv-table-no-translate::

Like csv-table, but the text inside the table is not translated. Useful when translation is handled by an external process, e.g. codelists.

included_cols is the optional list of indices of columns to include.

.. markdown::

A directive that renders its contents as markdown, using Recommonmark.

Source:

```{eval-rst}
.. markdown::

    Some markdown [a URL](http://example.org), `single backtick literals`.
```

Output:

Some markdown a URL, single backtick literals.

This is not so useful by itself, but allows markdown to be embedded inside other directives, e.g.:

Source:

```{eval-rst}
.. admonition:: Worked example
    :class: hint

    .. markdown::

        Some markdown [a URL](http://example.org), `single backtick literals`.
```

Output:

Worked example

Some markdown a URL, single backtick literals.

.. directory_list::

Return a bullet list for files in a directory.

path is the path of the directory.
url is a url prefix to form the links

Example:

Source:

```{eval-rst}
.. directory_list::
    :path: exampledir
    :url: https://github.com/OpenDataServices/sphinxcontrib-opendataservices/blob/master/docs/exampledir/
```

Output:

.. localization-note::

Create a note admonition that only will appear in languages that have “translated” it. This will not appear in the base language (normally English). If a translator wants to mark they have seen the message but do not want to add a note then they can leave a single hyphen ‘-’. The contents of the translation will be treated as markdown. The text within the directive should contain information useful for the translator and instruct what to do when they encouter this. For example:

```{eval-rst}
.. localization-note::

  DO NOT TRANSLATE THIS MESSAGE DIRECTLY

  Instead put some language specific context as to how to interpret this page.

  Put a '-' if you do not want this note to appear in this language.
```

Directives in other repositories