Declaring objects

Objects

.. syntax:grammar:: name

Directive for documenting grammars:

.. syntax:grammar:: MyGrammar

    Description.

Example output

grammar MyGrammar

Description.

Grammars can’t be nested, they also can’t appear inside production rules.

.. syntax:rule:: name

Directive for documenting production rules:

.. syntax:rule:: MyRule

    Description.

Example output

MyRule

Description.

Rules can’t be nested.

Parameters

All of the above directives accept the standard parameters:

:no-index:

:no-index-entry:

:no-contents-entry:

:no-typesetting:

The standard Sphinx options available to all object descriptions.

:name: <text>

Sets a human readable name for a rule or a grammar.

The primary name is used to refer to an object in documentation; it’s used in HTML paths, anchors, and serves as a unique object identifier.

The human readable name is used to display object to a user; it’s used when rendering documentation and cross-references.

Example:

.. syntax:grammar:: PrimaryName
    :name: Human readable name

    Notice that anchor for this grammar uses its primary name.

When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
When this cross-reference is rendered, though,
it will use a human readable name.

Example output

grammar Human readable name

Notice that anchor for this grammar uses its primary name.

When referring to an object, we use primary name: Human readable name. When this cross-reference is rendered, though, it will use a human readable name.

:imports: <list of diagram names>

If your parser generators allows importing grammars, you can use imports option to specify which diagrams are imported from the documented one.

This will affect object resolution for cross-references and diagrams.

Example:

.. syntax:grammar:: BaseGrammar

    .. syntax:rule:: BaseRule

.. syntax:grammar:: DownstreamGrammar
    :imports: BaseGrammar

    This grammar imports :syntax:g:`BaseGrammar`, so it can reference
    its rules without prefixing them with grammar name:
    :syntax:r:`BaseRule`.

    This also works in diagrams:

    .. syntax:diagram:: BaseRule

Example output

grammar BaseGrammar

BaseRule

grammar DownstreamGrammar

This grammar imports BaseGrammar, so it can reference its rules without prefixing them with grammar name: BaseRule.

This also works in diagrams:

:diagram-*:

You can add any option from syntax:diagram to an object description by prefixing it with diagram-. This option will be used in all diagrams that appear within object’s description.

Example:

.. syntax:grammar:: MyGrammar
    :diagram-end-class: simple

    All diagrams in this grammar will use simple end class:

    .. syntax:diagram:: Simple end class

    Unless they override it manually:

    .. syntax:diagram:: Complex end class
        :end-class: complex

Example output

grammar MyGrammar

All diagrams in this grammar will use simple end class:

Unless they override it manually:

Diagrams

.. syntax:diagram::

This directive renders a syntax diagram. Its contents should be a valid YAML document containing a description of a diagram element.

Full specification with examples is available in documentation for the syntax-diagrams library. You can also use an online diagram editor.

Example:

.. syntax:diagram::

    - "class"
    - non_terminal: "name"
    - optional:
      - "("
      - non_terminal: "class-bases"
      - ")"
    - ":"

Example output

Options:

:alt: <text>

Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users.

:align: top | middle | bottom | left | center | right

The alignment of the image, equivalent to the HTML <img> tag’s "align" attribute or the corresponding vertical-align and text-align CSS properties.

:class: <text>

Adds a CSS class to the corresponding <svg> or <img> element.

:end-class: simple | complex

Changes how ends of the diagram are rendered.

Simple	Complex

:reverse:

:no-reverse:

Switches diagram direction to right-to-left.

:svg-*:

:text-*:

Any other option from syntax_diagrams_svg_settings or syntax_diagrams_text_settings can be overridden as well. Replace all underscores in option name with dashes and add svg- or text- prefix:

Example:

.. syntax:diagram::
    :svg-padding: 15 10 15 10
    :svg-arc-margin: 15
    :svg-arrow-style: triangle

    choice:
    -
    - statement
    - expression
    default: 2

Example output

Simplified diagram directives

You can use ANTLR 4 syntax for simple diagrams. It’s quicker, but allows less customization.

.. syntax:lexer-diagram::

The body of this directive should contain a valid ANTLR 4 lexer rule description.

Example:

.. syntax:lexer-diagram:: ('+' | '-')? ([1-9][0-9]* | '0')

Example output

Options

All options from the syntax:diagram directive ara available, as well as syntax:autogrammar:cc-to-dash and syntax:autogrammar:literal-rendering.

.. syntax:parser-diagram::

The body of this directive should contain a valid ANTLR 4 parser rule description.

Example:

.. syntax:parser-diagram::

    SELECT DISTINCT? (
        '*' | expression (AS row_name)? (',' expression (AS row_name)?)*
    )

Example output

Options

All options from the syntax:diagram directive ara available, as well as syntax:autogrammar:cc-to-dash and syntax:autogrammar:literal-rendering.