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.