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.)