Configuration

User guide

Configuration

Modo🧯 can run based on a config file or standalone.

Config file

A Modo🧯 project is defined by a file modo.yaml. This file contains the complete configuration for the commands build and test. The modo.yaml is usually created with the command init (see project setup). The typical content of the generated file is shown at the bottom of this page.

When modo build or modo test are executed in a folder containing a modo.yaml, the file is used for configuration and no command line flags are required:

modo build

However, command line flags can still be used to overwrite the values that were read from the file. As an example, this is how to turn off warnings for missing docstrings:

modo build --report-missing false

All config file entries are also exposed as command line flags, except for pre- and post-processing scripts (pre-run, pre-build, pre-test, post-run, post-build, post-test).

Standalone

Modo🧯 can also be used without a modo.yaml config file. If there is no such file in the current directory, an empty configuration is used. Command line flags must be used for any configuration:

modo build -i api.json -o docs/

CLI flags

Most command line flags overwrite config file settings. These are not listed here explicitly. For details, see the config reference. There are, however, a few special flags that are useful to trigger different behaviour when working in different environments. These flags are available for both build and test command.

--config, -c

Use an alternative config file. Available for all commands, incl. init and clean.

--watch, -W

Re-run on changes of sources and documentation files. Disables all post-processing scripts after running them once. Together with the watch mode of your SSG (e.g. Hugo), this allows to preview changes in a web browser instantly.

--bare, -B

Don’t run pre- and post-processing scripts. May be useful when working in an environment where Mojo🔥 is not available.

--strict, -S

Exits with error on any warnings. Useful to ensure flawless docs in a CI.

--dry-run, -D

Dry-run without any file output. Useful for fast tests. Disables all post-processing scripts.

Paths

Paths in the config file as well as the directory structure created by the init command are just recommendations. Any other structure is possible, but requires adjustments to the config file, including pre- and post-processing scripts.

Paths are relative to the location of the file.

Config reference

The code listing below shows the content of modo.yaml as produced by modo init hugo for a package under src/mypkg.

modo.yaml

# Input files as generated by `mojo doc`.
# If a single directory is given, it is processed recursively.
input:
  - docs/src

# Source directories to monitor when running in watch mode.
source:
  - src/mypkg

# Full URLs of package sources. Used to create source links.
source-url:
  mypkg: https:/github.com/your/project/blob/main/src/mypkg

# Output directory.
output: docs/site/content

# Output directory for doc-tests.
# Remove or set to "" to disable doc-tests.
tests: docs/test

# Output format. One of (plain|hugo|mdbook).
format: hugo

# Re-structure docs according to package re-exports.
exports: true

# Use shortened cross-ref link labels.
short-links: true

# Report missing docstings and coverage.
report-missing: true

# Break with error on any warning.
strict: false

# Run without generating any output files.
dry-run: false

# Build for systems that are not case-sensitive regarding file names.
# Appends hyphen (-) to capitalized file names.
case-insensitive: false

# Directories to scan for templates to overwrite builtin templates.
templates: []

# Bash scripts to run before build as well as test.
pre-run:
  - |
    echo Running 'mojo doc'...
    magic run mojo doc -o docs/src/mypkg.json src/mypkg
    echo Done.

# Bash scripts to run before build.
pre-build: []

# Bash scripts to run before test.
# Also runs before build if 'tests' is given.
pre-test: []

# Bash scripts to run after test.
# Also runs after build if 'tests' is given.
post-test:
  - |
    echo Running 'mojo test'...
    magic run mojo test -I src docs/test
    echo Done.

# Bash scripts to run after build.
post-build: []

# Bash scripts to run after build as well as test.
post-run: []

Commands Features