smalldocs.extensions

Theme extensions: smalldocs add copies them from a git repository into _extensions/, and theme: finds them there.

bundled

source

bundled() -> list[str]

List the themes that come with smalldocs.

Parameter Type Default Description
returns list[str] The Bootswatch themes, and bootstrap

is_bootstrap

source

is_bootstrap(css: str) -> bool

Tell whether a stylesheet is a whole Bootstrap 5.3 theme: its variables, its colour modes and its components.

Parameter Type Default Description
css str required The text of a stylesheet
returns bool Whether it holds Bootstrap 5.3, as a Bootswatch theme does

css_name

source

css_name(name: str) -> str

Name a theme’s CSS file in the site: cosmo and my.css become cosmo.min.css and my.min.css, and x.min.css stays.

Parameter Type Default Description
name str required A Bootswatch name, such as cosmo, or a CSS file, such as styles/my.min.css
returns str The file’s name in site_libs/themes, such as cosmo.min.css

class Extension

source

Extension(name: str, path: Path, spec: dict = <factory>)

A theme in _extensions/<name>/ or _extensions/<org>/<name>/.

Parameter Type Default Description
name str required What theme: calls it: the name of its folder
path Path required Its folder
spec dict <factory> What its smalldocs.yml holds

Extension.file

source

Extension.file(key: str, value: object) -> PurePosixPath

Check that a file the extension names is inside its folder and is there.

Parameter Type Default Description
key str required A key of smalldocs.yml that names a file, such as logo
value object required Its value
returns PurePosixPath The file, from the extension’s folder

Extension.modes

source

Extension.modes() -> list[str]

List the modes of the theme: css: x.css has one, and css: {light, dark} can have two.

Parameter Type Default Description
returns list[str] light, and dark when the theme has one

Extension.css

source

Extension.css(mode: str) -> PurePosixPath

Find the CSS of a mode; a theme with one file uses it in both modes.

Parameter Type Default Description
mode str required light or dark
returns PurePosixPath The CSS file for that mode, from the extension’s folder

read_spec

source

read_spec(folder: Path) -> dict

Read an extension’s smalldocs.yml.

Parameter Type Default Description
folder Path required An extension’s folder
returns dict What its smalldocs.yml holds

find

source

find(root: Path) -> dict[str, list[Path]]

Find the themes in _extensions/<name>/ and _extensions/<org>/<name>/: the folders with a smalldocs.yml.

Parameter Type Default Description
root Path required The project folder
returns dict[str, list[Path]] Each theme’s name, and the folders that hold a theme of that name

installed

source

installed(root: Path) -> list[Path]

List the extensions in _extensions/: the folders, one or two levels down, with a smalldocs.yml or an _extension.yml.

Parameter Type Default Description
root Path required A project folder, or a cloned repository
returns list[Path] Each extension’s folder, for smalldocs or for Quarto

lookup

source

lookup(root: Path, name: str) -> Extension | None

Find the theme extension of a name; a name found twice, or also a Bootswatch name, is an error.

Parameter Type Default Description
root Path required The project folder
name str required A name in theme:
returns Extension | None The extension, or None when no extension has the name

css_files

source

css_files(css: Path, ext: Extension, warn: Callable[[str], None]) -> list[Path]

Find the local files that a stylesheet uses: fonts, images and other stylesheets in the extension’s folder.

Parameter Type Default Description
css Path required A CSS file in an extension
ext Extension required The extension
warn Callable[[str], None] required Called with a warning
returns list[Path] The files it uses through url(...) and @import, and the files those use

class Source

source

Source(text: str, url: str, ref: str | None = None, folder: bool = False)

Where smalldocs add gets extensions: a local folder, or a git repository at a ref.

Parameter Type Default Description
text str required The source as given; a local path is made absolute, so that .source works from any folder
url str required The folder, or the URL that git clones
ref str | None None The branch, tag or commit; None for the default branch
folder bool False Whether the source is a local folder, copied as it is

parse_source

source

parse_source(text: str) -> Source

Read the source of smalldocs add: org/repo is GitHub over ssh, and @ref picks a branch, tag or commit.

Parameter Type Default Description
text str required org/repo, org/repo@ref, a git URL, a local git repository, or a local folder
returns Source Where to get the extensions

git

source

git(*args: str, cwd: Path | None = None) -> CompletedProcess

Run git, and keep what it prints for the message when it fails.

Parameter Type Default Description
args str required The arguments of git
cwd Path | None None Where to run it
returns CompletedProcess What git returned

clone

source

clone(src: Source, dest: Path) -> str

Clone one commit of a repository: git clone --depth 1, or a fetch of the commit when the ref is a commit.

Parameter Type Default Description
src Source required A git repository and a ref
dest Path required An empty folder
returns str The commit that was cloned

copy_extension

source

copy_extension(src: Path, dest: Path, warn: Callable[[str], None]) -> None

Copy an extension’s folder without .git, .source or symbolic links.

Parameter Type Default Description
src Path required An extension’s folder in the clone or the local folder
dest Path required Its folder in the site
warn Callable[[str], None] required Called with a warning

ask_tty

source

ask_tty(question: str) -> bool | None

Ask a yes or no question in the terminal.

Parameter Type Default Description
question str required The question, which ends with [y/N]
returns bool | None The answer; None when there is no terminal to ask in

add

source

add(text: str, root: Path | str = '.', force: bool = False, ask: Callable[[str], bool | None] = <function ask_tty at 0x7f3b3a2144a0>) -> list[Path]

Copy each extension of a repository or a folder into the project’s _extensions/, and note where it came from.

Parameter Type Default Description
text str required The source: org/repo, org/repo@ref, a git URL, or a local folder
root Path | str '.' The project folder
force bool False Replace an extension that is already there, without asking
ask Callable[[str], bool | None] <function ask_tty at 0x7f3b3a2144a0> Asks before an extension is replaced
returns list[Path] The folders that were added

read_source

source

read_source(folder: Path) -> dict

Read where an extension came from.

Parameter Type Default Description
folder Path required An extension’s folder
returns dict Its .source: source, ref and commit; empty when it has none

themes

source

themes(root: Path | str = '.') -> int

Print the bundled themes, and the project’s extensions with where each came from.

Parameter Type Default Description
root Path | str '.' The project folder
returns int The exit code