click-extra refresh-directives - Refresh the self-updating blocks
embedded in Markdown files.
click-extra refresh-directives [OPTIONS]
PATHS...
Refresh the self-updating blocks embedded in Markdown files.
Walks each PATH (a Markdown file, or a directory scanned
recursively for Markdown sources) and rewrites every supported self-updating
block in place:
- matrix blocks (directive fences and marker regions alike),
regenerated from the project git history;
- python:render blocks carrying the :mirror: flag, whose Python
code is executed to regenerate the mirrored region below the fence (inserted
on first refresh);
- click:run blocks carrying both :screenshot: and :mirror:, whose
region below the fence links to the capture the block writes at build
time.
Examples nested inside longer code fences are never refreshed or
executed.
Pass --check to report stale blocks without writing; the command
then exits with a non-zero status, so a continuous-integration job can fail
on out-of-date documentation.
Refreshing reads the project git history and needs the sphinx
extra: install it with click-extra[sphinx]. Beware: mirror blocks are
arbitrary Python executed with the privileges of this process, so only
refresh documentation you trust, exactly as you would only build trusted
docs.
- PATHS...
- --check
- Do not write; exit with a non-zero status if any block is stale.
- --help /
-h
- Show this message and exit.
- --config
LOCATION
- Location of the configuration file. Supports local path with glob patterns
or remote URL.
- --no-config
- Ignore all configuration files and only use command line parameters and
environment variables.
- --validate-config
LOCATION
- Validate the configuration file and exit.
- --export-config
FORMAT
- Export the configuration in the selected format to <stdout>, then
exit.
[values: toml, yaml, json, json5, jsonc, hjson, xml, plist]
- --accessible
- Accessibility mode: disable colors and render tables in a borderless,
screen-reader-friendly format.
- --color[=auto|always|never]
- Colorize the output. A bare --color is the same as --color=always.
- --no-color
- Disable colorization (alias of --color=never).
- --progress /
--no-progress
- Show progress indicators during long operations. Disabled for
non-interactive output (pipes, dumb terminals, CI) and by
--accessible.
- --theme
[auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
- Color theme used for help screens.
- --table-format
FORMAT
- Rendering style of tables.
[values: aligned, asciidoc, colon-grid, csv, csv-excel, csv-excel-tab,
csv-unix, double-grid, double-outline, fancy-grid, fancy-outline, github,
grid, heavy-grid, heavy-outline, hjson, html, jira, json, json5, jsonc,
latex, latex-booktabs, latex-longtable, latex-raw, mediawiki, mixed-grid,
mixed-outline, moinmoin, orgtbl, outline, pipe, plain, presto, pretty,
psql, rounded-grid, rounded-outline, rst, simple, simple-grid,
simple-outline, textile, toml, tsv, unsafehtml, vertical, xml, yaml,
youtrack]
- --verbosity
LEVEL
- Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[values: CRITICAL, ERROR, WARNING, INFO, DEBUG]
- --verbose /
-v
- Increase the default WARNING verbosity by one level for each additional
repetition of the option.
- --quiet /
-q
- Decrease the default WARNING verbosity by one level for each additional
repetition of the option.
- --debug
- Shorthand for --verbosity DEBUG.
- REFRESH_DIRECTIVES_CHECK
- Do not write; exit with a non-zero status if any block is stale.
- REFRESH_DIRECTIVES__CLICK_DEFAULT_HELP
- Show this message and exit.
- REFRESH_DIRECTIVES_CONFIG
- Location of the configuration file. Supports local path with glob patterns
or remote URL.
- REFRESH_DIRECTIVES_VALIDATE_CONFIG
- Validate the configuration file and exit.
- REFRESH_DIRECTIVES_EXPORT_CONFIG
- Export the configuration in the selected format to <stdout>, then
exit.
- REFRESH_DIRECTIVES_ACCESSIBLE
- Accessibility mode: disable colors and render tables in a borderless,
screen-reader-friendly format.
- REFRESH_DIRECTIVES_COLOR
- Colorize the output. A bare --color is the same as --color=always.
- REFRESH_DIRECTIVES_NO_COLOR
- Disable colorization (alias of --color=never).
- REFRESH_DIRECTIVES_PROGRESS
- Show progress indicators during long operations. Disabled for
non-interactive output (pipes, dumb terminals, CI) and by
--accessible.
- REFRESH_DIRECTIVES_THEME
- Color theme used for help screens.
- REFRESH_DIRECTIVES_TABLE_FORMAT
- Rendering style of tables.
- REFRESH_DIRECTIVES_VERBOSITY
- Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
- REFRESH_DIRECTIVES_VERBOSE
- Increase the default WARNING verbosity by one level for each additional
repetition of the option.
- REFRESH_DIRECTIVES_QUIET
- Decrease the default WARNING verbosity by one level for each additional
repetition of the option.
- REFRESH_DIRECTIVES_DEBUG
- Shorthand for --verbosity DEBUG.
- REFRESH_DIRECTIVES_TIME
- Measure and print elapsed execution time.
- REFRESH_DIRECTIVES_PARAMS
- Show all CLI parameters, their provenance, defaults and value, then
exit.
- REFRESH_DIRECTIVES_TREE
- Show the tree of nested subcommands and exit.
- REFRESH_DIRECTIVES_MAN
- Read the command's manual page and exit.
- REFRESH_DIRECTIVES_HELP_FORMAT
- Render the command in the given format and exit.
- REFRESH_DIRECTIVES_VERSION
- Show the version and exit.
~/.config/click-extra/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}
- 0
- Success.
- 1
- A runtime error, or an aborted prompt (Ctrl-C, a declined
confirmation).
- 2
- A usage error: unknown option, invalid value, missing operand, or an
unparsable configuration file.