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."""
    write_template_formatted_sections()
    run(ctx, f'{python_m()} 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, 'prek uninstall')  # To prevent prek failures when mkdocs calls push
    run(ctx, f'{python_m()} mkdocs gh-deploy --force')
    with suppress(UnexpectedExit):
        run(ctx, 'prek install')  # Restore prek

get_out_dir

get_out_dir()

Returns the mkdocs-specified site directory.

Source code in calcipy/tasks/doc.py

def get_out_dir() -> Path:
    """Returns 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_m()} mkdocs serve --dirtyreload')