Roto Manual

This directory contains the source for Roto's manual.

Build the manual locally using the instructions below; this fork does not currently publish a hosted manual.

Writing

The source for this manual lives under docs/source and is written in reStructuredText and generated using Sphinx. The Sphinx documentation has a good primer on rST.

Building

1. Install uv.
2. Run make html to build the documentation. The generated docs will be in docs/build/html.
3. Sphinx doesn't always delete old files, so you sometimes have to run make clean if it starts to misbehave.

Serving

The easiest way to serve a local version of the docs is via python -m http.server -d docs/build/html.

Special Roto Features

Standard Library

The documentation for the standard library under source/reference/stc should not be edited directly because it is autogenerated. The following command will update it:

rm -r docs/source/reference/std
cargo run -- doc docs/source/reference/std

The command currently checks that the directory is empty to ensure that it doesn't have to delete any old files, that's why we need to empty it first.

The text in the generated files is based on the docstrings in src/runtime/basic.rs. These files are in Markdown instead of rST, using the MyST-Parser extension.

Roto References

We extended Sphinx with special references that link directly to Roto items. This is done with :roto:ref:`ITEM` where ITEM is the name of the item you want to refer to. For example, :roto:ref:`bool`.

Roto Syntax Highlighting

This manual also supports syntax highlighting for Roto code. To use it, just specify roto as the name of the language like so:

.. code-block:: roto

    fn main() {
        print("This is Roto code!");
    }