Colophon: Monte Documentation Build Tools

Restructured text

The docs are written in restructured text.

Sphinx

The docs are built with Sphinx and hosted on readthedocs.

The virtualenv for building the docs is separate from the main Monte virtualenv. Create a separate virtualenv and pip install -r docs_requirements.txt, then make html to make the docs. Locally built docs will show up in the docs/build directory.

Syntax Railroad Diagrams and Haskell Parser

rr_ext.py is an extension that integrates the railroad-diagrams library by Tab Atkins into the build process. It provides a custom .. syntax:: directive.

If syntax_dest is set in conf.py, the syntax diagram info is written to a file in JSON format. download:rr_grammar.py converts this format to a sphinx grammar production display.

download:rr_happy.py is work-in-progress to generate a haskell monadic parser.

Doctests

Use make doctest to extract the source/docs_examples.mt test suite from the documentation. Then run it a la typhon loader test docs_examples.

TODO List

Todo

discuss bindings. Expand this section to “slots and bindings”? or discuss bindings under auditors?

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/auditors.rst, line 101.)

Todo

expansion of various forms of try

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 147.)

Todo

while doctests, expansion

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 176.)

Todo

for doctests, expansion

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 204.)

Todo

doctest /** docstring */

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 235.)

Todo

interface syntax diagram @@s

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 342.)

Todo

various items marked “@@” in railroad diagrams. Also, finish re-organizing them around precedence (use haskell codegen to test).

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/block-expr.rst, line 349.)

Todo

finish grammar productions marked @@. Meanwhile, see monte_parser.mt for details.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/grammar.rst, line 8.)

Todo

When new packaging efforts are ready, update this to mention that module namespaces are either the stdlib or a package name.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/modules.rst, line 55.)

Todo

special operator rules because of security

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/operators.rst, line 30.)

Todo

VERB_ASSIGN lexical details

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/operators.rst, line 128.)

Todo

discuss, doctest SlotExpression &x, BindingExpression &&x

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/operators.rst, line 490.)

Todo

named args in argList

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/operators.rst, line 567.)

Todo

discuss matchers in object expressions

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/operators.rst, line 584.)

Todo

document docstrings

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/ordinary-programming.rst, line 59.)

Todo

document named args, defaults

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/ordinary-programming.rst, line 61.)

Todo

show: Guards play a key role in protecting security properties.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/ordinary-programming.rst, line 268.)

Todo

Fix the module.name notation resulting from abuse of sphinx python support.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/runtime.rst, line 9.)

Todo

When Bool is fixed to reveal its interface, re-run mtDocStrings to document and, or, xor, not, butNot, pick, op__cmp.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/runtime.rst, line 13.)

Todo

Fix the module.name notation resulting from abuse of sphinx python support.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/runtime.rst, line 2599.)

Todo

discuss SlotExpr

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/semantics.rst, line 208.)

Todo

discuss sameness and doctest _equalizer

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/semantics.rst, line 256.)

Todo

specify canStartIndentedBlock, braceStack exactly

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/symbols.rst, line 26.)

Todo

Document how to compile and run such a script.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/monte/checkouts/latest/docs/source/taste.rst, line 33.)