Documentation

This section describes the documentation tools and provides guidelines for writing documentation.

Tools

This documentation is written with the Sphinx documentation generator. Sphinx is the tool that transforms the documentation into a website and other output formats. Documentation can be found in their website:

Formats

ReStructuredText is the main documentation format used by Sphinx. Documentation can be found at:

Markdown is also supported, but is less powerful for technical documentation purposes. It is supported through the recommonmark extension. To use markdown, just create .md files and link them in a toctree.

Converting formats with Pandoc

Pandoc is a documentation format converting tool. It can be used to convert between various documentation formats. On macOS with Homebrew, it can be installed with brew install pandoc.

Conversion is performed by passing the from and to flags. For example, to convert Markdown to ReStructuredText, run the following command:

pandoc --from=markdown --to=rst file.md --wrap=preserve > file.rst

See their manual for more info.

Bibliographies

BibTeX bibliographies and citations are supported through the sphinxcontrib-bibtext extension.

To create a separate bibliography for a chapter use a label and key prefix as follows:

Syntactic completions :cite:`s-AmorimEWV16`

.. bibliography:: ../../../../bib/spoofax.bib
   :style: plain
   :labelprefix: S
   :keyprefix: s-

Customizing HTML with CSS and JavaScript

The _static directory contains a style.css and script.js file to customize the HTML output.

Writing guide

General guidelines

Each chapter in the manual, i.e. a top-level entry in the table of contents should start with a paragraph that explains what the chapter is about, including a definition of the thing it documents. For example: “Stratego is a language for defining program transformations …”

Meta-language documentation

Standard documentation ingredients for meta-language documentation:

  • Introduction
    • main concepts and a small example
    • how does it fit in the bigger picture?
  • Reference manual
    • a systematic description of all language features
    • include schematic descriptions
    • use examples for illustration
  • Configuration
    • how to build it
    • configuration options (yaml, esv, stratego hooks)
    • how to call it / use it
  • Examples
    • typical examples
    • examples for some specific features
    • pointers to real projects
  • Bibliography
    • list with all or at least key publications
    • discussion of what each publication contributes

It probably makes sense to put each of these in a separate section.