# Roto Manual
This directory contains the source for Roto's manual.
The manual is hosted at [roto.docs.nlnetlabs.nl](https://roto.docs.nlnetlabs.nl).
## 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](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
## Building
1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/).
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](https://myst-parser.readthedocs.io/en/latest/).
### 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!");
}
```