Write Documentation#

This page gives the rules for the text, the page layout, the diagrams and the generated pages of this site.

Build the Site#

The site uses MkDocs with the Material theme. The configuration is mkdocs.yml in the repository root.

Create the conda environment one time.

conda env create -f Documentation/environment.yml

Activate the environment.
```
conda activate acres-docs
```
Build the site in strict mode.
```
mkdocs build --strict
```
Expected Result

The last line is Documentation built in N seconds. The folder site contains the pages. The build stops when a page has a warning.
Start the preview server when you write pages.
```
mkdocs serve
```
Expected Result

The server shows the site at http://127.0.0.1:8000. The page updates when you save a file.

The theme and one plugin print a notice about MkDocs 2 before each build. The environment acres-docs sets the variables DISABLE_MKDOCS_2_WARNING and NO_MKDOCS_2_WARNING, which hide the two notices.

File	Function
`mkdocs.yml`	The navigation, the theme options and the Markdown extensions.
`Documentation/Stylesheets/acres.css`	The design tokens and all style rules of the site.
`Documentation/JavaScripts/mathjax.js`	The MathJax configuration.
`Documentation/Tools/hooks.py`	Puts the SVG diagrams into the pages. Adds the header pages to the navigation.
`Documentation/Tools/gen_api.py`	Generates the reference pages from the source code.
`Documentation/Tools/ste_check.py`	Examines the text for the language rules.
`Documentation/Tools/titlecase.py`	Examines the headings for title case. The option `--fix` corrects them.
`Documentation/Tools/check_docs.py`	Examines the links, the diagrams and the coverage of the reference pages.
`Documentation/requirements.txt`	The Python packages of the build.
`Documentation/environment.yml`	The conda environment of the build.

Deploy to Cloudflare Pages#

The production project is acres-docs at acres-docs.pages.dev. Deploy only the built site. Keep credentials outside the repository.

Activate the documentation environment and install Node.js 22 or later.

Sign in to Cloudflare in the browser.

npx --yes wrangler@4.146.0 login --scopes account:read user:read pages:write

For a new account, create the project one time.
```
npx --yes wrangler@4.146.0 pages project create acres-docs --production-branch main --force
```
The --force option creates a Pages project directly. Use it only for project creation.
Build, check and deploy the documentation.
```
bash Documentation/Tools/deploy_pages.sh
```
Expected Result

The script prints the deployment URL. The production site uses the main branch. The script removes its temporary build folder after the upload.

For a remote shell, add --device --browser=false to the login command. Approve the code at the URL that Wrangler prints.

Set PYTHON to select the Python interpreter. Set ACRES_PAGES_PROJECT to deploy to a different project. An automated upload needs CLOUDFLARE_ACCOUNT_ID and a CLOUDFLARE_API_TOKEN with Pages edit permission. Store these values in the automation service, not in source files. Refer to Cloudflare Direct Upload.

Language Rules#

Use the ASD-STE100 Simplified Technical English rules below for the pages, captions and README.md. The project keeps the spelling exception stated below. The automated checker does not certify full dictionary compliance.

Rule	Limit
Sentence in a procedure	20 words maximum. Use the imperative. Give one instruction in each sentence.
Sentence in a description	25 words maximum. Give one topic in each sentence.
Paragraph	6 sentences maximum.
Voice	Active voice.
Tense	Simple present, simple past and simple future.
Words	No idioms. No phrasal verb when one approved verb exists. No contractions.
Terms	One term for one thing. The Glossary gives the terms.
Technical names	You can use names such as ROS 2, LiDAR, Bekker and Pacejka.
Procedures	Numbered steps.
Safety notes	WARNING, CAUTION and Note.

Use these words: "must" for an obligation, "can" for an ability, "do not" for a prohibition. Do not use "should", "may", "might", "could" or "would". Write "for example" and "that is". Do not write Latin abbreviations.

The spelling is British English, for example "tyre", "metre" and "centre". This is a deviation from ASD-STE100. The source code, the data keys and the UI text of the project use this spelling.

Run the checker before each commit.

python Documentation/Tools/ste_check.py
python Documentation/Tools/ste_check.py --warnings Documentation/Models/lidar.md

The checker stops on errors: long sentences, long paragraphs, contractions, words that STE does not approve and first person. The option --warnings also shows possible passive voice and tenses that STE does not approve. Read each warning and write the sentence again when the warning is correct. The checker does not examine the generated pages, because those pages copy the comments of the source code.

Terms#

Use the term of the Glossary each time. Do not use a second word for the same thing. Add a term to the glossary before you use a new term on a page. Write the names of files, options, topics and identifiers as code, for example -SensorRecord.

Page Types#

Each page has one type. The type sets the structure.

Type	Section	Structure
Overview	Overview	A short description, a diagram, cards with links.
Procedure	Get Started, Tutorials	A goal, the conditions before you start, numbered steps with expected results, next steps.
Model	Models	Scope and assumptions, symbols, equations, parameter tables, a code map, limitations, references.
Reference	API Reference	An index table, then one reference row for each item.
Design	Design	A decision, its reason and its cost.
Development	Development	Rules and procedures for contributors.

The first paragraph after the title is the summary of the page. Keep it to two sentences.

Procedure Pages#

Start with the section "Before You Start". List the conditions that are necessary. Write each step as a numbered list item. Put the command in a code block below the step. Put the result that the user must see in a result block.

1. Start the game at the default spawn.

    ```sh
    Packaged/Linux/Acres.sh -VehicleDemo
    ```

    !!! result "Expected Result"
        The Maxxum is in front of the ICSC garage.

Model Pages#

A model page gives the full mathematics of one model. Use these sections in this sequence.

Scope and Assumptions. State what the model computes and what the model ignores.
Symbols. A table with the columns Symbol, Quantity and Unit.
One section for each part of the model. Give the equations and name the source function.
Parameters. A parameter table for each configuration file.
Code Map. A table with the columns Item, File and Function.
Limitations.
References. The publications of the model.

Use SI units. State the unit of each symbol. Read each number from the source code or the shipped configuration.

Page Elements#

Headings#

Write headings in title case. Each heading has an anchor. Run the title-case tool to correct the headings.

python Documentation/Tools/titlecase.py --fix

Safety Notes#

Use the three levels of ASD-STE100. Put the safety note before the step that it applies to.

Level	Use
WARNING	A risk of injury to persons. For example a command that can move the real vehicle.
CAUTION	A risk of damage to equipment or loss of data.
Note	Information that helps the user.

!!! warning "WARNING"
    Do not send drive-by-wire commands outside the DDS loopback fence. The real vehicle can move.

!!! caution "CAUTION"
    Close the editor before you package the game. An open editor can corrupt the cooked assets.

!!! note "Note"
    The first build compiles several thousand shaders.

WARNING

Do not send drive-by-wire commands outside the DDS loopback fence. The real vehicle can move.

CAUTION

Close the editor before you package the game. An open editor can corrupt the cooked assets.

Note

The first build compiles several thousand shaders.

Parameter Tables#

All parameter tables have the same columns: Name, Type, Unit, Default and Description. Leave a cell empty when it does not apply. Write the name as code.

| Name | Type | Unit | Default | Description |
|---|---|---|---|---|
| `mass_kg` | number | kg | 6520 | The mass of the chassis without ballast. |

Name	Type	Unit	Default	Description
`mass_kg`	number	kg	6520	The mass of the chassis without ballast.

Reference Rows#

A reference page shows a description on the left and an example panel on the right. On a narrow screen the panel moves below the description. Write one row for each item. A row is a div with the class ref and two inner div elements. Keep a blank line after each opening tag and before each closing tag. Hide the table of contents of a reference page with hide: [toc] in the front matter.

<div class="ref" markdown>
<div markdown>

### `-SensorRecord`

Records the sensors of the vehicle from the start of the session.

| Name | Type | Unit | Default | Description |
|---|---|---|---|---|
| `-SensorOutput=` | path | | session folder | The folder of the recording. |

</div>
<div markdown>

=== "Shell"

    ```sh
    Packaged/Linux/Acres.sh -VehicleDemo -SensorRecord
    ```

</div>
</div>

`-SensorRecord`#

Records the sensors of the vehicle from the start of the session.

Name	Type	Unit	Default	Description
`-SensorOutput=`	path		session folder	The folder of the recording.

ShellPython

Packaged/Linux/Acres.sh -VehicleDemo -SensorRecord

import subprocess
subprocess.run(["Packaged/Linux/Acres.sh", "-VehicleDemo", "-SensorRecord"])

Language Tabs#

Use tabs when an example exists in more than one language. Use these tab names and this sequence: Shell, Python, C++, ROS 2 CLI. A tab selection applies to all tab groups of the site.

Mathematics#

MathJax shows the equations. Write an inline formula as \( ... \) and a display formula as \[ ... \]. Define each symbol in the symbols table of the page.

\[ F_x = \mu(s)\, F_z \]

\[ F_x = \mu(s)\, F_z \]

Cards#

An overview page can show links as cards.

<div class="cards" markdown>
<div markdown>

**[Get Started](../GetStarted/install.md)**

Install the tools and build the game.

</div>
</div>

Diagrams#

Each diagram is a hand-written SVG file in Documentation/Assets/Diagrams. Refer to a diagram with the image syntax. The title in quotation marks is the caption.

![The data flows of ACRES](../Assets/Diagrams/system-overview.svg "The components of ACRES and the four data flows.")

The build puts the SVG into the page. The SVG then reads the color tokens of the page theme. One file is thus correct in the light theme and in the dark theme.

Obey these rules.

Set a viewBox and the class acres-diagram on the svg element. Do not set a fixed width.
Copy the style element from Documentation/Assets/Diagrams/diagram-style.css. Do not change it.
Use only the classes of the table below. Do not write a color value in an element.
Add a title element with a short description.
Align the shapes to a grid of 10 units. Keep text at 11 units or larger.
Keep the width of the viewBox at 880 units or less. A page shows the diagram at this size at most.
Put a label on each arrow that is not obvious.
Write the labels in the same terms as the pages.
Do not use script or foreignObject.

Class	Use
`d-bg`	The background rectangle.
`d-group`	A panel that contains a group of boxes.
`d-box`	A neutral box.
`d-box-a` to `d-box-e`	A box of one of the five color groups.
`d-title`, `d-label`, `d-text`, `d-note`, `d-mono`, `d-cap`	Text: title, box label, body, small note, code, small capitals.
`d-edge`	A neutral line or arrow.
`d-edge-a` to `d-edge-e`	A line of a color group.
`d-dash`	A dashed line. Add it to an edge class.
`d-head`, `d-head-a` to `d-head-e`	The fill of an arrow head in a `marker`.
`d-fill-a` to `d-fill-e`, `d-fill-ink`, `d-fill-muted`	Text or a small shape in a group color.
`d-halo`	Text on a line. The class adds an outline in the background color.

The color groups have one meaning in all diagrams.

Group	Color	Meaning
a	Green	Simulation: the models, the physics and ACRES Core.
b	Blue	Interfaces: ROS 2, the bridges and the sockets.
c	Amber	Data: logs, bags, datasets and configuration files.
d	Violet	Learning: training, policies and evaluation.
e	Red	The real vehicle and safety limits.

Examine each diagram in both themes before a commit.

python Documentation/Tools/check_docs.py --diagrams

Generated Pages#

The build generates these pages from the source code. Do not edit them.

Page	Source
C++ Headers	The `///` comments of the headers in `Acres/Source/Acres`, `Core/Source` and the ROS 2 packages.
Messages	The `.msg` and `.srv` files of `ROS/acres_interfaces`.
Menu Settings	The parameter table in `AcresSession.cpp` and the shipped configuration files.
Option Index	The `FParse` calls of the game source.

The generator is Documentation/Tools/gen_api.py. MkDocs runs it on each build. To see the generated Markdown without a build, run the generator alone.

python Documentation/Tools/gen_api.py --out build/api-preview

A header comment uses this format.

/// @file
/// One paragraph that describes the header.

/// One sentence that describes the function.
///
/// Args:
///     SpeedMps: The forward speed of the vehicle.
/// Returns: The rolling resistance in newtons.
double RollingResistanceN(double SpeedMps);

Checks before a Commit#

Do these steps in the repository root.

Correct the headings.

python Documentation/Tools/titlecase.py --fix

Examine the language.

python Documentation/Tools/ste_check.py

Build the site in strict mode.
```
mkdocs build --strict
```
Examine the links, the diagrams and the coverage of the built site.
```
python Documentation/Tools/check_docs.py
```
Expected Result

Each tool prints zero errors.