doc

Document CLI.

Functions

build

build(ctx)

Build documentation with mkdocs.

Source code in calcipy/tasks/doc.py

@task()
def build(ctx: Context) -> None:
    """Build documentation with mkdocs."""
    auto_doc_path = get_doc_subdir().parent / 'modules'
    write_autoformatted_md_sections()
    delete_dir(auto_doc_path)
    _diagram_task(ctx, auto_doc_path)

    # Find and trim trailing whitespace
    for path_md in auto_doc_path.rglob('*.md'):
        trim_trailing_whitespace(path_md)

    run(ctx, f'{python_dir()}/mkdocs build --site-dir {get_out_dir()}')

deploy

deploy(ctx)

Deploy docs to the Github gh-pages branch.

Source code in calcipy/tasks/doc.py

@task()
def deploy(ctx: Context) -> None:
    """Deploy docs to the Github `gh-pages` branch."""
    if _is_mkdocs_local():  # pragma: no cover
        raise NotImplementedError('Not yet configured to deploy documentation without "use_directory_urls"')

    with suppress(UnexpectedExit):
        run(ctx, 'pre-commit uninstall')  # To prevent pre-commit failures when mkdocs calls push
    run(ctx, f'{python_dir()}/mkdocs gh-deploy --force')
    with suppress(UnexpectedExit):
        run(ctx, 'pre-commit install')  # Restore pre-commit

get_out_dir

get_out_dir()

Retrieve the mkdocs-specified site directory.

Source code in calcipy/tasks/doc.py

@beartype
def get_out_dir() -> Path:
    """Retrieve the mkdocs-specified site directory."""
    mkdocs_config = read_yaml_file(get_project_path() / MKDOCS_CONFIG)
    return Path(mkdocs_config.get('site_dir', 'releases/site'))

watch

watch(ctx)

Serve local documentation for local editing.

Source code in calcipy/tasks/doc.py

@task()
def watch(ctx: Context) -> None:
    """Serve local documentation for local editing."""
    if _is_mkdocs_local():  # pragma: no cover
        path_doc_index = get_out_dir() / 'index.html'
        open_in_browser(path_doc_index)
    else:  # pragma: no cover
        webbrowser.open('http://localhost:8000')
        run(ctx, f'{python_dir()}/mkdocs serve --dirtyreload')