Usage

Warning

Still WIP.

Object Type Definiton

Before descibing any object, we need to tell extension “what data consist of the object and how to display it”.

The object type definiton does this. A definition is a python dict, consists of two main parts: Schema (Data) and Templates (Presentation):

cat = {
    'schema': {
        'name': 'str, ref, uniq',
        'attrs': {
            'color': 'str, ref',
        },
        'content': 'str'
    },
    'templates': {
        'obj':"Hi there, human! I've got **{{ color }}** fur.",
        'header': '🐈 {{ name }}',
        'ref': '``🐈 {{ name }}``',
    }
}

The Field Definiton DSL

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:

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

Roles

Same to sphinx:xref-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`

1

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`

:any:cat.id:`1`

Indices

According to sphinx documentation, we use sphinx:ref-role 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`

any-cat.id

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 :any:tmplvar:`objtype` and :any:tmplvar:`title` are available.

Ambiguous Reference Template

Applied when the reference is ambiguous.

Hint

In this template, only variables :any:tmplvar:`objtype` and :any:tmplvar:`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: