sphinx-asdf

sphinx-asdf is a plugin for sphinx that enables generation of documentation from ASDF schemas.

Installation

To install the latest release on PyPI:

$ pip install sphinx-asdf

The latest development version is available from the main branch on github. To clone the project:

$ git clone https://github.com/asdf-format/sphinx-asdf

To install:

$ cd sphinx-asdf
$ pip install .

To install in development mode:

$ pip install -e .

Usage

The sphinx-asdf plugin provides two sphinx directives, asdf-autoschemas and asdf-schema.

The plugin also provides several configuration variables:

asdf_schema_path
asdf_schema_standard_prefix
asdf_schema_reference_mappings

Basic Example

Consider a package with the following layout as an example:

mypackage/
   setup.py
   mypackage/
      schemas/
         example.org/
            custom/
               foo/
                  a.yaml
                  b.yaml
                  c.yaml
               bar/
                  x.yaml
                  y.yaml
                  z.yaml
      ...
   docs/
      conf.py
      schemas.rst

This package provides schemas with tags that all have the prefix of tag:example.org/custom. The layout of the schema directory reflects this naming convention. We wish to provide documentation for all of our schemas.

First, we will add configuration variables to our docs/conf.py file:

# This variable indicates the top-level directory containing schemas.
# The path is relative to the location of conf.py in the package
asdf_schema_path = "../mypackage/schemas"
# This variable indicates the standard prefix that is common to all schemas
# provided by the package.
asdf_schema_standard_prefix = "example.org/custom"

The variables set in the docs/conf.py file indicate to sphinx-asdf where to locate the schemas based on the names we will use in the documentation.

Now, we use the asdf-autoschemas directive in docs/schemas.rst to create a table of contents for the schema documentation:

.. asdf-autoschemas::

   foo/a
   foo/b
   foo/c
   bar/x
   bar/y
   bar/z

Each item in the list represents the name of a schema to be included in the documents. The names are not paths to the schema files and should not include the file extension. Resolution of the names to actual schema files is handled by the asdf_schema_path and asdf_schema_standard_prefix configuration variables.

We can also use multiple asdf-autoschemas directives if we wish:

These schemas are part of foo:

.. asdf-autoschemas::

   foo/a
   foo/b
   foo/c

And these schemas are part of bar:

.. asdf-autoschemas::

   bar/x
   bar/y
   bar/z

When sphinx-build runs, the sphinx-asdf plugin will automatically generate schema documentation for each of the schemas listed in each asdf-autoschemas directive. In the documentation, each asdf-autoschemas directive will be replaced with a table of contents that contains links to each of the listed schema documents.

Directive settings

While the asdf_schema_path and asdf_schema_standard_prefix configuration variables set global schema resolution settings, it is also possible to set per-directive settings. For example, we could have done the following:

.. asdf-autoschemas::
   :schema_root: ../mypackage/schemas
   :standard_prefix: example.org/custom

This would eliminate the need to set global settings. It also allows any global settings to be overridden on a per-directive basis.

Note

The :schema_root: argument requires a path that is relative to the sphinx configuration file.

External References

Schema references to other schemas in the same package are automatically converted to links in the generated documentation. (This assumes that all of the references correspond to schemas that are explicitly generated by an asdf-autoschemas directive). However, sometimes it is necessary to resolve references to schemas in other packages. The asdf_schema_reference_mapping configuration variable is provided for this purpose. It enables a mapping between references that begin with a particular prefix to a URL indicating another package's documentation.

For example, to enable references to the ASDF Standard documentation to be resolved as links, include the following in your docs/conf.py file:

asdf_schema_reference_mappings = [
    (
        "tag:stsci.edu:asdf",
        "http://asdf-standard.readthedocs.io/en/latest/generated/stsci.edu/asdf/",
    ),
]

Inline documentation

The asdf-autoschemas directive automatically generates individual schema documentation pages and creates a table of contents. However, sometimes it may be useful to include schema documentation inline inside another document. The asdf-schema directive is provided for this purpose.

Using the package described above as an example, the asdf-schema directive can be used to document a single schema inside of another document:

.. asdf-schema::

   foo/a

The behavior of the asdf-schema directive is also governed by the asdf_schema_path and asdf_schema_standard_prefix global configuration variables. The directive also accepts the same :schema_root: and :standard_prefix: arguments as asdf-autoschemas (see Directive settings above) for per-directive configuration.

Contributing

We welcome feedback and contributions to the project. Contributions of code, documentation, or general feedback are all appreciated. Please follow the contributing guidelines to submit an issue or a pull request.

We strive to provide a welcoming community to all of our users by abiding to the Code of Conduct.