Usage

Defining Schema

What is Schema?

Before descibing any object, we need a “schema” to tell extension “how to descibe the object”. For extension user, “schema” is a python object that can specific in configuration value ⚙️any_schemas.

The necessary python classes for writing schema are listed here:

class any.Schema(objtype, name=Field(form=<Form.PLAIN: 1>, unique=True, referenceable=True, required=False), attrs={}, content=Field(form=<Form.PLAIN: 1>, unique=False, referenceable=False, required=False), description_template='{{ content }}', reference_template='{{ title }}', missing_reference_template='{{ title }} (missing reference)', ambiguous_reference_template='{{ title }} (disambiguation)')

Create a Schema instance.

Parameters:

• objtype (str) – The unique type name of object, it will be used as basename of corresponding Directives, Roles and Indices

• name (Field) – Constraints of optional object name

• attrs (dict[str, Field]) – Constraints of object attributes

• content (Field) – Constraints of object content

• description_template (str) – See Description Template

• reference_template (str) – See Reference Template

• missing_reference_template (str) – See Reference Template

• ambiguous_reference_template (str) – See Reference Template

Class-wide shared special keys used in template rendering context:

TYPE_KEY = 'type'

Template variable name of object type

NAME_KEY = 'name'

Template variable name of object name

CONTENT_KEY = 'content'

Template variable name of object content

TITLE_KEY = 'title'

Template variable name of object title

class any.Field(form=Form.PLAIN, unique=False, referenceable=False, required=False)

Describes value constraint of field of Object.

The value of field can be single or mulitple string.

Parameters:

• form (Form) – The form of value.

• unique (bool) –

  Whether the field is unique. If true, the value of field must be unique within the scope of objects with same type. And it will be used as base string of object identifier.

  Only one unique field is allowed in one object type.

  Note

  Duplicated value causes a warning when building documentation, and the corresponding object cannot be referenced correctly.

• referenceable (bool) – Whether the field is referenceable. If ture, object can be referenced by field value. See Roles for more details.

• required (bool) – Whether the field is required. If ture, ObjectError will be raised when building documentation if the value is no given.

class any.Field.Form(value)

An enumeration represents various string forms.

PLAIN = 1

A single string

WORDS = 2

Mulitple string separated by whitespace

LINES = 3

Mulitple string separated by newline(\n)

Documenting Object

Once a schema created, the corresponding Directives, Roles and Indices will be generated. You can use them to descibe, reference and index object in your documentation.

For the convenience, we use default domain name “any”, and we assume that we have the following schema with in ⚙️any_schemas:

from textwrap import dedent
from any import Schema, Field

cat = Schema('cat',
    name=Field(referenceable=True, form=Field.Form.LINES),
    attrs={
        'id': Field(unique=True, referenceable=True, required=True),
        'color': Field(referenceable=True),
        'picture': Field(),
    },
    description_template=dedent("""
        .. image:: {{ picture }}
           :align: left

        :Cat ID: {{ id }}
        :Color: {{ color }}

        {{ content }}"""),
    reference_template='🐈{{ title }}',
    missing_reference_template='😿{{ title }}',
    ambiguous_reference_template='😼{{ title }}')

Directives

Object Description

The aboved schema created a Directive named with “domain:objtype” (In this case, it is any:cat) for descibing object(INC, it is cat🐈).

Arguments

Arguments are used to specify the {{name}} of the object. The number argument is depends on the name any.Field of Schema.

• A None field means no argument is required

• For a non-None Field, see any.Field for more details

Specially, If first argument is _ (underscore), the directive must be located after a Section Title, the text of section title is the real first argument.

In this case, the any:cat directive accepts multiple argument split by newline.

Options

All attributes defined in schema are converted to options of directive. Further, they will available in various Templates.

• A None field is no allowed for now means no argument is required

  Hint

  May be changed in the future vesrion.

• For a non-None Field, see any.Field for more details

In this case, the directive has three options: id, color and picture.

Content

Content is used to specify the {{content}} of the object.

• A None field means no content is required

• For a non-None Field, see any.Field for more details

In this case, the directive accepts content.

The directive will be rendered to a reStructuredText snippet, by Description Template, then inserted to documentation.

Let’s documenting such a cat:

.. any:cat:: Nyan Cat
             Nyan_Cat
   :id: 1
   :color: pink gray
   :picture: _images/nyan-cat.gif

   :any:cat:`Nyan Cat` is the name of a YouTube video uploaded in April 2011,
   which became an internet meme. The video merged a Japanese pop song with
   an animated cartoon cat with a Pop-Tart for a torso, flying through space,
   and leaving a rainbow trail behind it. The video ranked at number 5 on
   the list of most viewed YouTube videos in 2011. [#]_

   .. [#] https://en.wikipedia.org/wiki/Nyan_Cat

It will be rendered as:

Nyan Cat

Cat ID:

1

Color:

pink gray

🐈Nyan Cat is the name of a YouTube video uploaded in April 2011, which became an internet meme. The video merged a Japanese pop song with an animated cartoon cat with a Pop-Tart for a torso, flying through space, and leaving a rainbow trail behind it. The video ranked at number 5 on the list of most viewed YouTube videos in 2011. [1]

[1]

https://en.wikipedia.org/wiki/Nyan_Cat

Roles

Same to Cross-referencing syntax, explicit title :role:`title <target>` is supported by all the Roles. If not explicit title specific, reference title will be rendered by one of Reference Template.

General Reference

The aboved schema created a role named with “domain-objtype” (In this case, it is any:cat) for creating a reference to Object Description. The interpreted text can be value of any referenceable field.

Reference by name	:any:cat:`Nyan Cat`	🐈Nyan Cat
By another name	:any:cat:`Nyan_Cat`	Nyan_Cat
By ID	:any:cat:`1`	🐈Nyan Cat
Explicit title	:any:cat:`This cat <Nyan Cat>`	This cat
A nonexistent cat	:any:cat:`mimi`	mimi

Field-Specific Reference

Role “domain-objtype.field” will be created for all referenceable Fields (In this case, it is any:cat.name, any:cat.id and any:cat.color).

These roles also create reference to Object Description. But the interpreted text must be value of field in role’s name.

Reference by name	:any:cat.name:`Nyan Cat`	🐈Nyan Cat
By ID	:any:cat.id:`1`	🐈Nyan Cat

Indices

According to sphinx documentation, we use Cross-referencing arbitrary locations to create reference to object indices, and the index name should prefixed with domain name.

General Index

Index “domain-objtype” (In this case, it is any-cat) creates reference to object index which grouped by all referenceable field values.

:ref:`any-cat`

Cat Reference Index

Field Specific Index

Index “domain-objtype.field” will be created for all reference Fields (In this case, it is any-cat.name, any-cat.id and any-cat.color).

These indices create reference to object index which grouped by specific field values.

:ref:`any-cat.name`	Cat Name Reference Index
:ref:`any-cat.id`	Cat Id Reference Index

Writing Template

We use Jinja as our templating engine.

Currently we need two kinds of template to let .

Description Template

Used to generate object description. Can be written in reStructuredText.

Reference Template

Used to generate object reference. Only plain text is allowed for now.

Reference Template has two various variants:

Missing Reference Template

Applied when the reference is missing.

Hint

In this template, only variables {{objtype}} and {{title}} are available.

Ambiguous Reference Template

Applied when the reference is ambiguous.

Hint

In this template, only variables {{objtype}} and {{title}} are available.

Variables

For the usage of Jinja’s variable, please refer to Jinja’s Variables.

All attributes defined in schema are available as variables in template. Note the value of variable might be string or string list (depends on value of any.Schema.Field.Form).

Beside, there are some special variable:

objtype

Type:

str

Type of object.

Tip

Name of variables(“objtype”) can be changed by setting TYPE_KEY

name

Type:

Union[None,str,List[str]]

Name of object.

Tip

Name of variables(“name”) can be changed by setting NAME_KEY

content

Type:

Union[None,str,List[str]]

Content of object.

Tip

Name of variables(“content”) can be changed by setting CONTENT_KEY

title

Type:

str

Title of object.

In Reference Template, its value might be overwritten by explicit title.

Tip

Name of variables(“title”) can be changed by setting TITLE_KEY

Filters

For the usage of Jinja’s filter, please refer to Jinja’s Filters.

All Jinja’s Builtin Filters are available. In additional, we provide the following custom filters to enhance the template:

install(fn)

Copy a file in Sphinx srcdir to outdir, return the URI of file which relative to current documentation.

The relative path to srcdir will be preserved, for example, {{ fn | install }} while fn is _images/foo.jpg, the file will copied to <OUTDIR>/_any/_images/foo.jpg, and returns a POSIX path of fn which relative to current documentation.

Added in version 1.0.

Changed in version 2.3: Renamed from copyfile to install

thumbnail(imgfn)

Changes the size of an image to the given dimensions and removes any associated profiles, returns a a POSIX path of thumbnail which relative to current documentation.

This filter always keep the origin aspect ratio of image.

Added in version 1.0.

Changed in version 2.3: Width and height arguments are not accepted for now.