chartbook.build_docs

chartbook.build_docs#

Module Contents#

Classes#

IncrementalBuildSummary

What an incremental build redid.

Functions#

generate_docs

Generate documentation by running both pipeline publish and sphinx build.

get_docs_src_path

Get the path to the docs_src directory included in the package.

run_build_markdown

Run the pipeline publish script to generate markdown files.

run_mkdocs_build

Run mkdocs build over the project in _docs_dir; the site lands in _build/html.

run_sphinx_build

Run sphinx-build to generate HTML files.

API#

class chartbook.build_docs.IncrementalBuildSummary[source]#

What an incremental build redid.

Attributes: fresh: True if the build tree was rebuilt from empty. reason: Why, when fresh is True. regenerated: Pipelines whose pages were generated. reused: Pipelines whose pages were kept from the previous build. sources_written: Files written into the Sphinx project because they were new or their content had changed. sources_deleted: Files removed from it because nothing produces them any more. rendered: Whether Sphinx was run. It is not when no source changed and the last render succeeded. pages_read: Source pages Sphinx re-read (added plus changed), or None if that could not be read from its output. output_written: Files written to the output directory.

describe() → str[source]#

One line for the console.

fresh: bool#

None

output_written: int#

None

pages_read: int | None#

None

reason: str#

None

regenerated: list[str]#

None

rendered: bool#

None

reused: list[str]#

None

sources_deleted: int#

None

sources_written: int#

None

chartbook.build_docs.generate_docs(output_dir: pathlib.Path, project_dir: pathlib.Path, publish_dir: pathlib.Path = Path('./_output/to_be_published/'), _docs_dir: pathlib.Path = Path('./_docs'), keep_build_dirs: bool = False, temp_docs_src_dir: pathlib.Path = Path('_docs_src'), should_remove_existing: bool = False, size_threshold: float = 50, strict: Optional[bool] = None, strip_mathjax2: bool = True, incremental: bool = False, after_build: bool = False)[source]#

Generate documentation by running both pipeline publish and sphinx build.

Parameters:

  • output_dir (Path) – Directory where output will be generated.

  • project_dir (Path) – Root directory of the project.

  • publish_dir (Path) – Directory where files will be published.

  • _docs_dir (Path) – Directory where documentation will be built.

  • keep_build_dirs (bool) – If True, keeps temporary build directory after generation.

  • temp_docs_src_dir (Path) – Temporary directory for documentation source files.

  • should_remove_existing (bool) – If True, removes existing output directory after successful generation.

  • size_threshold (float) – File size in MB above which a dataframe page does not read the file for its date range.

  • strict (bool | None) – None (the default) errors and exits when source files are missing, except that a lone pipeline that has built none of its outputs yet (see :func:chartbook.conf_validation.built_nothing) is rendered, with a warning and each of them shown as not built. True, what --strict asks for, errors on that one too. False skips the pipelines that have missing files, with warnings, and renders a lone pipeline that has built nothing as None does.

  • strip_mathjax2 (bool) – If True, strip Plotly’s MathJax 2 scripts from notebook outputs to prevent conflicts with Sphinx’s MathJax 3. Defaults to True.

  • incremental (bool) – If True, keep _docs_dir between builds and redo only what changed since the last one: pipelines whose inputs are unchanged are not regenerated, and Sphinx re-renders only pages whose source differs. The output directory is updated in place. Defaults to False, a clean build.

  • after_build (bool) – True when the pipeline’s build script has just run, as in chartbook build. An output still missing then is one the build did not make, and is an error even when it is all of them.

Returns:

For an incremental build, a summary of what was redone. None otherwise.

Return type:

IncrementalBuildSummary or None

chartbook.build_docs.get_docs_src_path(pipeline_theme: str = 'pipeline', writer: str = 'sphinx')[source]#

Get the path to the docs_src directory included in the package.

Parameters:

  • pipeline_theme (str) – Theme to use for pipeline documentation.

  • writer (str) – The site tool, sphinx or mkdocs; each has its own theme folders.

Returns:

Path to the docs_src directory.

Return type:

Path

chartbook.build_docs.run_build_markdown(project_dir: pathlib.Path, pipeline_theme: str = 'catalog', publish_dir: pathlib.Path = Path('./_output/to_be_published/'), _docs_dir: pathlib.Path = Path('./_docs'), docs_src_dir: pathlib.Path = Path('_docs_src'), size_threshold: float = 50, skip_pipelines: set[str] | None = None, reuse_pipelines: set[str] | None = None, code_times: dict[str, str] | None = None, hash_cache=None, built_index: dict | None = None)[source]#

Run the pipeline publish script to generate markdown files.

Parameters:

  • project_dir (Path) – Root directory of the project.

  • pipeline_theme (str) – Theme to use for pipeline documentation.

  • publish_dir (Path) – Directory where files will be published.

  • _docs_dir (Path) – Directory where documentation will be built.

  • docs_src_dir (Path) – Directory containing documentation source files.

  • size_threshold (float) – File size in MB above which a dataframe page does not read the file for its date range.

  • skip_pipelines (set[str] | None) – Set of pipeline IDs to skip due to missing files.

  • reuse_pipelines (set[str] | None) – Set of pipeline IDs whose existing pages an incremental build is keeping, so they are not regenerated.

  • code_times (dict[str, str] | None) – Code-change times already known, by pipeline ID.

chartbook.build_docs.run_mkdocs_build(_docs_dir: pathlib.Path) → str[source]#

Run mkdocs build over the project in _docs_dir; the site lands in _build/html.

Raises:

RuntimeError – If MkDocs fails; its output is in the message.

chartbook.build_docs.run_sphinx_build(_docs_dir: pathlib.Path)[source]#

Run sphinx-build to generate HTML files.

Sphinx keeps its cache under _docs_dir/_build. When that directory survives from an earlier build, Sphinx re-reads only the source files that are newer than its cache and re-renders only their pages.

Parameters:

_docs_dir (Path) – Directory where documentation is built.

Returns:

What sphinx-build printed to standard output.

Return type:

str

Raises:

RuntimeError – If the sphinx-build command fails.