Skip to main content

atmos.docs

The atmos.docs function runs atmos docs through the current Atmos executable. Use it to generate documentation artifacts, such as a README, from the docs.generate sections of atmos.yaml.

Usage​

atmos.docs(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.docs("generate", "readme") runs atmos docs generate readme.

SubcommandPurpose
generateGenerate a documentation artifact defined under docs.generate in atmos.yaml.

Without a subcommand, the bare call atmos.docs() opens the Atmos documentation, and atmos.docs("vpc") displays the documentation for the vpc component. See the atmos docs command reference for details.

note

Calling atmos.docs without a subcommand opens or displays documentation for people to read, so it is rarely useful from a script. The generate subcommand writes files and works well in automation.

Arguments​

*positionals

(Optional) Strings placed on the command line right after docs, in order: the subcommand and its positional arguments, such as the name of the docs.generate section to run, or a component name. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. The generate subcommand takes no flags of its own beyond the global ones.

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Generate a README​

atmos.docs("generate", "readme")

Regenerate several artifacts​

for artifact in ["readme", "release-notes"]:
    atmos.docs("generate", artifact)

Each name must match a section under docs.generate in atmos.yaml.

Related​