Quickstart

Installation

1. Install sphinx-syntax using Pip:

   $ pip install sphinx-syntax
   

2. Add it to the extensions list in your conf.py:

   extensions = [
       "sphinx_syntax",
   ]
   

3. If you plan to extract documentation from grammar files, set syntax_base_path in your conf.py:

   # Path to the folder containing grammar files,
   # relative to the directory with `conf.py`.
   syntax_base_path = "../grammars/"
   

4. If you’re building LaTeX documentation, add an extension to convert SVGs to PDFs:

   $ pip install 'sphinxcontrib-svg2pdfconverter[CairoSVG]'
   

   extensions = [
       # ...
       "sphinxcontrib.cairosvgconverter",
   ]
   

   Tip

   See extension’s README if you want to use Inkscape or RSVG instead of CairoSVG.

Declaring objects

Use syntax:grammar to create grammars, and syntax:rule to create production rules:

.. syntax:grammar:: MyGrammar

    A grammar for my DSL.

    .. syntax:rule:: root

        The root grammar rule.

Example output

grammar MyGrammar

A grammar for my DSL.

root

The root grammar rule.

Cross-referencing objects

Use syntax:grammar (syntax:g) and syntax:rule (syntax:r) to cross-reference grammars and rules:

Grammar :syntax:g:`MyGrammar` has a root rule :syntax:r:`MyGrammar.root`.

Example output

Grammar MyGrammar has a root rule MyGrammar.root.

Rendering diagrams

Use syntax:diagram to create syntax diagrams. Diagrams described using YAML format, its structure is detailed in documentation for the syntax-diagrams library. You can also use an online diagram editor.

.. syntax:diagram::

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

Example output

Alternatively, you can use ANTLR 4 syntax to describe diagrams. It’s quicker, but allows less customization. See syntax:lexer-diagram and syntax:parser-diagram:

.. syntax:parser-diagram:: 'class' name ('(' classBases ')')? ':'
    :literal-rendering: contents-unquoted
    :cc-to-dash:

Example output

Automatic documentation generation

Use syntax:autogrammar and provide it with a path to a grammar definition file relative to syntax_base_path:

.. syntax:autogrammar:: Json.g4