Metadata-Version: 2.1
Name: sphinx-asdf
Version: 0.2.4
Summary: Sphinx plugin for generating documentation from ASDF schemas
Author-email: The ASDF Developers <help@stsci.edu>
License: Copyright (c) 2021 Association of Universities for Research in Astronomy.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: documentation, https://sphinx-asdf.readthedocs.io/en/stable
Project-URL: repository, https://github.com/asdf-format/sphinx-asdf
Project-URL: tracker, https://github.com/asdf-format/sphinx-asdf/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: asdf
Requires-Dist: astropy >=5.0.4
Requires-Dist: docutils
Requires-Dist: mistune >=3
Requires-Dist: packaging
Requires-Dist: sphinx
Requires-Dist: sphinx-astropy
Requires-Dist: sphinx-rtd-theme
Requires-Dist: toml
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'

sphinx-asdf
===========

.. image:: https://github.com/asdf-format/sphinx-asdf/workflows/CI/badge.svg
    :target: https://github.com/asdf-format/sphinx-asdf/actions
    :alt: CI Status

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

.. code-block:: python

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

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:

.. code-block:: python

   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 <CONTRIBUTING.md>`__ 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 <CODE_OF_CONDUCT.md>`__.


.. Links

.. _ASDF: https://asdf-standard.readthedocs.io/en/latest
.. _sphinx: https://www.sphinx-doc.org/en/master
.. _on github: https://github.com/asdf-format/sphinx-asdf
.. _development mode: https://packaging.python.org/tutorials/distributing-packages/#working-in-development-mode
.. _sphinx directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
.. _table of contents: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
