smalldocs.config

Read a project’s _smalldocs.yml, or its _quarto.yml: the options smalldocs knows, merged as Quarto merges them, and the ones it ignores.

class ConfigError

source

A project that smalldocs cannot build, with a message that says why.

class BuildError

source

A build that cannot go on, with a message that says why.

class Project

source

Project(root: Path, config: dict, warnings: list[str] = <factory>, file: str = '_quarto.yml')

A website project: its folder, its merged config, and what smalldocs did not understand in it.

Parameter	Type	Default	Description
`root`	Path	required	The folder that holds the config
`config`	dict	required	The whole config, as read
`warnings`	list[str]	`<factory>`	One line for each key or feature that smalldocs ignores
`file`	str	`'_quarto.yml'`	The name of the config file: `_smalldocs.yml` or `_quarto.yml`

Project.html_options

source

Project.html_options() -> dict

The project-wide page options: top-level keys, then format.html in _quarto.yml.

Parameter	Type	Default	Description
returns	dict		The options that apply to every page, before a page’s own

section

source

section(cfg: dict, key: str) -> dict

Read a section of the config; one that is not a mapping is an error.

Parameter	Type	Default	Description
`cfg`	dict	required	The whole config
`key`	str	required	A top-level key, such as `website`
returns	dict		Its value, or an empty dict when it is missing

as_list

source

as_list(v: object) -> list

Make a config value that may be one item or a list into a list.

Parameter	Type	Default	Description
`v`	object	required	A config value that may be one item or a list
returns	list		The value as a list: None is empty, a single value is one item

filter_paths

source

filter_paths(cfg: dict) -> list[str]

List the paths in filters, which Quarto gives as a string or as a {path: ...} entry.

Parameter	Type	Default	Description
`cfg`	dict	required	The merged config
returns	list[str]		The path of each filter

glob_regex

source

glob_regex(pattern: str) -> Pattern

Turn a glob into a regex as Quarto reads globs: * and ? stop at /, ** crosses folders.

Parameter	Type	Default	Description
`pattern`	str	required	A glob, such as `posts/.qmd` or `images/*`
returns	Pattern		A regular expression for whole paths

glob_match

source

glob_match(path: str, pattern: str) -> bool

Match a path against a glob as Quarto does: * inside one folder, ** across; a glob with no / matches at any depth.

Parameter	Type	Default	Description
`path`	str	required	A path relative to the root, with `/`
`pattern`	str	required	A glob relative to the root; a leading `/` is the root
returns	bool		Whether the path matches

read_yaml

source

read_yaml(path: Path) -> object

Read a YAML file; a syntax error becomes a ConfigError that names the file.

Parameter	Type	Default	Description
`path`	Path	required	A YAML file
returns	object		What it holds

merge

source

merge(a: dict, b: dict) -> dict

Merge two option dicts as Quarto does: the nearer one wins, key by key.

Parameter	Type	Default	Description
`a`	dict	required	The options from further out
`b`	dict	required	The options from nearer the page, which win
returns	dict		A new dict; nested dicts are merged, lists and values replaced

check_keys

source

check_keys(cfg: dict, known: dict, path: str) -> list[str]

List the keys of the config that smalldocs does not read.

Parameter	Type	Default	Description
`cfg`	dict	required	A part of the config
`known`	dict	required	What smalldocs knows of that part
`path`	str	required	Where the part is, for the message
returns	list[str]		A line for each key that smalldocs ignores

load

source

load(root: Path | str) -> Project

Read a project’s _smalldocs.yml, or else its _quarto.yml, and note what smalldocs will ignore.

Parameter	Type	Default	Description
`root`	Path \| str	required	A folder that holds `_smalldocs.yml` or `_quarto.yml`, or the file itself
returns	Project		The project

check_native

source

check_native(proj: Project, others: list[str]) -> Project

Check a _smalldocs.yml: its sections, and the keys that smalldocs does not read.

Parameter	Type	Default	Description
`proj`	Project	required	A project read from `_smalldocs.yml`
`others`	list[str]	required	The other config files beside it, which smalldocs does not read
returns	Project		The same project, with its warnings

dir_metadata

source

dir_metadata(project: Project, rel: Path) -> dict

Merge the _metadata.yml files of the page’s folders, as Quarto does.

Parameter	Type	Default	Description
`project`	Project	required	The project
`rel`	Path	required	A page’s path, relative to the root
returns	dict		The options from every `_metadata.yml` between the root and the page, nearest last