Sphinx Extensions

Overview 

cikit provides reusable Sphinx roles and directives for embedding CI data and generated artifacts directly into reStructuredText documentation.

The recommended entry point is the bundled extension:

extensions = [
    "cikit.sphinx_ext",
]

It enables all cikit Sphinx extensions:

Extension	RST element	Purpose
`cikit.sphinx_ext.metrics`	`cikit-metric` role	Render a value from the local cikit data cache as inline text.
`cikit.sphinx_ext.chart`	`cikit-chart` directive	Embed an SVG chart interactively in HTML with an image fallback.
`cikit.sphinx_ext.log`	`cikit-log` directive	Embed a log file as a collapsible HTML block with a literal fallback.
`cikit.sphinx_ext.hash`	`cikit-hash` role	Render a compact SHA-256 digest with tooltip and clipboard support.

The individual extensions remain standalone Sphinx extensions. Projects that only need a subset may enable them separately.

Enabling the Extensions 

Recommended Configuration 

For normal cikit documentation, enable the package extension once:

extensions = [
    "cikit.sphinx_ext",
]

The package extension loads all cikit roles and directives through the regular Sphinx extension mechanism.

This is the recommended configuration because new cikit Sphinx features become available without adding another entry to conf.py.

Selective Configuration 

Projects may still enable individual extensions explicitly:

extensions = [
    "cikit.sphinx_ext.metrics",
    "cikit.sphinx_ext.hash",
]

This is useful when a project deliberately wants to expose only a subset of the available cikit RST elements.

Do not enable both the bundle and the same individual extension merely for completeness. The bundle is sufficient when all cikit extensions are wanted.

cikit-metric 

cikit.sphinx_ext.metrics provides the inline cikit-metric role.

It resolves values from locally cached cikit run data during the Sphinx build.

Basic Usage 

A metric target uses the form:

<run>.<key>

For example:

Build time: :cikit-metric:`build.build_time` seconds.

Warnings: :cikit-metric:`build.warnings`

If the local cache contains:

CIKIT_DATA_DIR/
`-- build.json

with:

{
    "build_time": 4.2,
    "warnings": 3
}

the rendered text contains:

Build time: 4.2 seconds.

Warnings: 3

Run Selection 

The first component selects the logical run.

For:

:cikit-metric:`coverage.coverage`

the role reads:

<cikit_data_dir>/coverage.json

and resolves the key:

coverage

Nested Keys 

Only the first dot separates the run name from the data key.

The remaining key may itself be dotted.

For example:

:cikit-metric:`build.memory.flash.used`

is interpreted as:

run = build
key = memory.flash.used

This allows the role to address nested dictionaries supported by the cikit data lookup helpers.

Data Directory 

The metrics extension defines the Sphinx configuration value:

cikit_data_dir

It must point to the local cikit data cache.

When documentation is built through the cikit Sphinx macro, this value is supplied automatically through the Sphinx command line:

-D cikit_data_dir=${CIKIT_DATA_DIR}

A direct Sphinx invocation must provide the value separately, for example in conf.py:

cikit_data_dir = "../public/cikit_data"

It may also be supplied through sphinx-build -D.

Local Data Only 

cikit-metric reads local run cache files directly.

It does not:

query the remote cikit Data API
perform a timeline query
resolve values from artifact metadata

The required run data must therefore already be available in the configured local data directory when Sphinx is built.

Error Behavior 

The Sphinx build fails when:

the target does not follow <run>.<key>
cikit_data_dir is not configured
the requested metric cannot be resolved

A numeric value of 0 is valid and is rendered normally.

cikit-chart 

cikit.sphinx_ext.chart provides the cikit-chart directive for SVG charts.

Basic Usage 

Example:

.. cikit-chart:: ../_static/artifacts/chart_build.svg
   :alt: Build history
   :width: 100%

The directive takes exactly one argument: the URI of the SVG chart.

Options 

Supported options are:

Option	Default	Purpose
`alt`	`Interactive chart`	Accessible description and fallback link text.
`width`	`100%`	Width used for HTML and non-HTML output.
`height`	not set	Optional explicit chart height.
`class`	none	Additional CSS classes.

The directive always adds the CSS class:

cikit-chart

Example with all optional layout settings:

.. cikit-chart:: ../_static/artifacts/chart_build.svg
   :alt: Build history
   :width: 90%
   :height: 420px
   :class: report-chart

HTML Output 

For HTML builders, the SVG is embedded using an HTML object element rather than an img element.

Conceptually:

<object
    class="cikit-chart"
    data="../_static/artifacts/chart_build.svg"
    type="image/svg+xml">
    ...
</object>

This keeps interactive behavior and JavaScript contained in Pygal SVG output active in the generated documentation.

The object also contains a normal link to the SVG as fallback content.

Non-HTML Output 

For non-HTML builders, cikit-chart emits a regular Docutils image node.

The same URI, alternative text, width, height, and CSS classes are reused where applicable.

Chart Files 

cikit-chart does not query cikit data and does not create charts.

It embeds an already existing SVG.

A typical cikit workflow is:

historical cikit data
        |
        v
   TimelineChart
        |
        v
 TIMELINE artifact
        |
        v
   Sphinx prepare
        |
        v
docs/_static/artifacts/chart_*.svg
        |
        v
cikit-chart directive

Generated cikit reports use this mechanism for registered TIMELINE artifacts.

For timeline creation, see Timeline Charts.

cikit-log 

cikit.sphinx_ext.log provides the cikit-log directive for command and build logs.

Basic Usage 

Example:

.. cikit-log:: ../_static/artifacts/cmake-build.log

The argument is the log file URI relative to the current RST source file.

Options 

Supported options are:

Option	Default	Purpose
`title`	Filename	Display title of the log block.
`open`	not set	Start the HTML log block expanded.
`class`	none	Additional CSS classes.

The directive always adds the CSS class:

cikit-log

Example:

.. cikit-log:: ../_static/artifacts/cmake-build.log
   :title: CMake Build Output
   :open:
   :class: build-log

Path Resolution 

Unlike cikit-chart, the log extension actively reads the referenced file during the Sphinx build.

The URI is resolved relative to the RST source file containing the directive.

For example, when:

docs/_generated/build.rst

contains:

.. cikit-log:: ../_static/artifacts/cmake-build.log

the extension resolves the log file relative to:

docs/_generated/

The resolved file is also registered as a Sphinx dependency.

Changes to the log can therefore participate in Sphinx dependency tracking.

HTML Output 

HTML output uses the native details element.

Conceptually:

<details class="cikit-log">
    <summary>cmake-build.log</summary>
    <p>Download log</p>
    <pre>...</pre>
</details>

Logs are collapsed by default.

Using:

:open:

adds the HTML open attribute and initially expands the log.

The HTML representation also contains a download link to the original log file.

The HTML representation includes built-in styling provided by the cikit.sphinx_ext.log extension. Projects using the extension do not need to provide additional CSS for the default log presentation.

The styling separates log blocks visually from surrounding documentation and keeps long log lines inside the available content width. Existing line breaks and indentation are preserved while overly long lines and tokens may wrap.

The following CSS classes are available for project-specific customization:

cikit-log
cikit-log-content

Additional classes supplied through the class option are added to the outer details element.

Non-HTML Output 

Non-HTML builders receive a regular Docutils container containing:

a rubric with the log title
a link to the log
a literal block containing the log contents

This keeps the log readable when collapsible HTML elements are unavailable.

Reading Logs 

Log files are read as UTF-8.

Invalid byte sequences are replaced rather than causing decoding to fail.

If the referenced file cannot be read, the directive raises a Sphinx error and the documentation build fails.

HTML Escaping 

Log content, titles, and generated HTML attributes are escaped before being inserted into raw HTML.

Log text containing characters such as < or > is therefore displayed as text rather than interpreted as HTML markup.

cikit-hash 

cikit.sphinx_ext.hash provides the inline cikit-hash role for SHA-256 digests.

The role is intended for build reports and release documentation where an artifact checksum should remain fully available without placing a 64-character digest directly into the visible table layout.

Basic Usage 

Use the role with a complete SHA-256 digest:

Package hash:
:cikit-hash:`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

The role syntax is inline RST syntax. cikit-hash is not a directive.

It can also be used directly inside a sentence or table cell:

SHA-256: :cikit-hash:`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

Accepted Values 

The role accepts exactly one complete SHA-256 digest:

exactly 64 hexadecimal characters
uppercase and lowercase hexadecimal input are accepted
the value is normalized to lowercase before rendering

An invalid value raises a Sphinx error and fails the documentation build.

The role does not calculate the hash of a file. The complete digest must already be known when the RST is generated.

HTML Output 

For HTML builders, only the first 12 hexadecimal characters are shown followed by an ellipsis.

For example:

0123456789ab…

The complete digest remains available in the generated HTML:

the title attribute shows SHA-256: <digest> on mouse-over
the complete value is stored in the data-hash attribute
clicking the hash copies the complete digest when the browser Clipboard API is available
keyboard users can trigger the same copy action with Enter or Space

Conceptually, the generated HTML is similar to:

<code
    class="cikit-hash"
    data-hash="0123456789abcdef..."
    title="SHA-256: 0123456789abcdef..."
    role="button"
    tabindex="0">
    0123456789ab…
</code>

Clipboard support is registered by the extension through Sphinx itself. No additional JavaScript file has to be added to the consuming project’s html_static_path.

Whether clipboard access is granted is controlled by the browser. The tooltip and shortened display remain available even when clipboard access is not.

Non-HTML Output 

Non-HTML builders receive the complete 64-character digest as a literal value.

No checksum information is therefore lost when documentation is rendered to a format without interactive HTML behavior.

Typical Report Usage 

A generated package or build-artifact table may use the role like this:

.. list-table:: Packages
   :header-rows: 1

   * - Artifact
     - Size
     - SHA-256
   * - ``cikit-0.1.0.tar.gz``
     - 82 KiB
     - :cikit-hash:`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

The report generator is responsible for calculating or retrieving the digest and emitting the role.

The Sphinx extension is responsible only for validating and presenting it.

Artifact Integration 

The chart and log extensions are especially useful together with cikit artifacts. cikit-hash complements them by presenting checksums associated with downloadable artifacts.

During:

sphinx.prepare(env, docs_dir)

registered artifacts are copied into the Sphinx source tree.

The current mapping is:

RST
    -> docs/_generated/

BADGE
    -> docs/_static/badges/

other artifact types
    -> docs/_static/artifacts/

This means registered:

TIMELINE artifacts
LOG artifacts
BUILD artifacts
BUNDLE artifacts
other regular artifacts

are available below the static artifact directory during the documentation build.

Generated Reports 

cikit report helpers generate RST references for supported artifacts.

Timeline artifacts are rendered with:

.. cikit-chart:: ../_static/artifacts/chart_build.svg
   :width: 100%

Log artifacts are rendered with:

.. cikit-log:: ../_static/artifacts/cmake-build.log

Artifact hashes may be rendered with:

:cikit-hash:`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

The generated report therefore refers to prepared artifacts through stable Sphinx paths while checksum presentation remains independent of the original build directory.

Direct Use 

The cikit Sphinx extensions are not limited to content originally generated by cikit.

For example:

cikit-chart can embed any suitable SVG reachable from the documentation output
cikit-log can embed any readable text file available relative to the RST source
cikit-hash can render any valid SHA-256 digest
cikit-metric can render values from any compatible local cikit run-data file

The cikit artifact workflow is useful because it gives generated CI outputs stable locations before Sphinx is invoked.

Builder Behavior 

The extensions are designed to preserve useful information outside HTML output.

Element	HTML	Non-HTML
`cikit-metric`	Inline text	Inline text
`cikit-chart`	Interactive SVG `object`	Image node
`cikit-log`	Collapsible `details` block	Container with literal log block
`cikit-hash`	Compact interactive digest	Complete literal SHA-256 digest

cikit-chart, cikit-log, and cikit-hash provide builder-specific representations where required.

Relationship to Sphinx Build Support 

The extensions provide RST-level rendering features.

The Sphinx macro provides workflow integration:

cleaning generated Sphinx input directories
copying registered artifacts
running sphinx-build
configuring the cikit data directory
registering the completed HTML documentation as a FOLDER artifact

The two layers deliberately remain separate:

cikit macros
    -> prepare data and artifacts
    -> run Sphinx

cikit.sphinx_ext
    -> render cikit-specific RST elements

This allows the extensions to be used in documentation projects independently of the full cikit Sphinx workflow.

For the build workflow, see Sphinx Documentation Build.

Sphinx Extensions

Overview 

Enabling the Extensions 

Recommended Configuration 

Selective Configuration 

cikit-metric 

Basic Usage 

Run Selection 

Nested Keys 

Data Directory 

Local Data Only 

Error Behavior 

cikit-chart 

Basic Usage 

Options 

HTML Output 

Non-HTML Output 

Chart Files 

cikit-log 

Basic Usage 

Options 

Path Resolution 

HTML Output 

Built-in Styling 

Non-HTML Output 

Reading Logs 

HTML Escaping 

cikit-hash 

Basic Usage 

Accepted Values 

HTML Output 

Non-HTML Output 

Typical Report Usage 

Artifact Integration 

Generated Reports 

Direct Use 

Builder Behavior 

Relationship to Sphinx Build Support 

See Also 