View on GitHub


MAGMA documentation generator


This is an experimental documentation generator for the MAGMA computer algebra system.


Install the Tatsu package (e.g. pip install tatsu) used for parsing.

Run the Python 3 script with the source files as arguments. It will output some files in markdown format containing documentation. Example:

$ python3 -o output_dir source.mag another_source.mag


The source files are either:

For MAGMA files, line comments beginning /// (but not ////) are special doc comments with meanings described below. Markdown files are interpreted as if each line is a doc comment (without the leading ///).

If a filename starts with ///, it is interpreted as a single doc comment; this is useful to put files into sections without editing the source.

If an intrinsic does not have any documentation attached to it via doc comments, then we consider the {}-delimited docstring instead. If it is {"} then the intrinsic is grouped with the previous (the same as for ///ditto), otherwise the contents become documentation for the intrinsic.

Example magma file:

///# My module
///This documents the first section.

///## Introduction
/// This documents the introduction.
/// More information about the introduction

///## Main intrinsics

/// This documents Aardvark.
intrinsic Aardvark() -> []
  {This is ignored.}
end intrinsic;

intrinsic Bear() -> []
  {This documents Bear.}
end intrinsic;

/// This documents both Cat and Dog together.
intrinsic Cat() -> []
end intrindic;

intrinsic Dog() -> []
end intrinsic;

intrinsic Elephant() -> []
  {Elephant is undocumented.}
end intrinsic;

///~intrinsic Fish() -> []
///~  {This documents Fish, even though it is in a comment.}
///~end intrinsic

// four or more slashes are ignored //


The main parser is in which is generated using the Tatsu python package from magma.ebnf with the command python3 -m tatsu -o magma.ebnf.


Copyright (C) 2018 Christopher Doris

This is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this. If not, see