Reusable base class for documentation-style reports with sidebar navigation, collapsible panels, and PDF export.
Class: Report in factory.report/package.core/ObjReportDocumentation.py
Inherits from: ObjData.ObjData
Companion YAML: ObjReportDocumentation.yaml
ObjReportDocumentation provides a palette-driven documentation layout
suitable for any report that presents structured content in a
browsable, printable format. It handles all shared concerns (CSS grid
layout, sidebar filtering, panel expand/collapse, PDF generation,
Mermaid diagram rendering) so that subclasses only need to supply
page content.
The companion ObjReportDocumentation.yaml contains four resource
namespaces loaded by the base class:
| Key | Purpose |
|---|---|
css.report |
Full CSS stylesheet using only --ax-* palette variables |
js.main |
Shared JavaScript (toggle, filter, PDF export) |
html.page |
Outer page template with sidebar and main content areas |
html.panel |
Accordion panel template for each page |
html.sidebar_item |
Sidebar navigation item template |
html.sidebar |
Sidebar container template |
When a subclass has its own companion YAML, the base class YAML is
merged first, then the subclass YAML is overlaid on top. This means
subclasses only need to define their own additional keys (e.g.
subclass-specific JS). HTML and CSS templates are inherited
automatically from ObjReportDocumentation.yaml.
All CSS classes use the doc-* prefix to avoid collisions with
other report styles. Colours reference only --ax-* CSS custom
properties injected by ObjCss from the active palette, ensuring
automatic theme compliance.
The layout uses CSS grid with two columns:
1fr flexible widthOn screens narrower than 768px the sidebar hides and content goes
full-width (responsive breakpoint).
The js.main resource provides the following global functions:
| Function | Description |
|---|---|
toggleDocPanel(id) |
Toggle a single panel open/closed |
openDocPanel(id) |
Open a specific panel and scroll to it |
expandAllPanels() |
Expand every panel on the page |
collapseAllPanels() |
Collapse every panel on the page |
toggleAllPanels() |
Toggle between all-expanded and all-collapsed |
filterDocSidebar() |
Filter sidebar items by search input text |
generateDocPDF() |
Export the document as PDF (see Print/PDF below) |
The _load_resources method adds the following libraries via
CdnConstants:
Override three methods to create a concrete documentation report:
get_title() -> strReturn the report title displayed in the header.
get_subtitle(param1="", param2="") -> strReturn the subtitle/description line. Parameters are passed through
from the report engine.
build_pages(param1="", param2="", param3="") -> list[dict]Return a list of page dictionaries. Each dict represents one
collapsible panel in the output:
| Key | Type | Description |
|---|---|---|
title |
str | Panel heading text |
icon |
str | Font Awesome icon class (e.g. "fa-book") |
badge |
str | Badge label (e.g. method name, category) |
badge_color |
str | Bootstrap badge colour name (primary, success, etc.) |
sections |
str | Pre-rendered HTML content for the panel body |
Use these in build_pages() to compose the sections HTML:
render_section(title, icon, content, color="")Titled content block with a horizontal separator. Wraps arbitrary
HTML content under a heading with an icon.
render_table(headers, rows)Palette-themed HTML table using the ax-tbl class. headers is a
list of strings; rows is a list of lists.
render_code_block(content, lang="")Syntax-highlighted code block compatible with highlight.js. Braces
are preserved as literals.
render_mermaid(diagram)Wraps a Mermaid diagram definition in the appropriate <div> for
client-side rendering. The Mermaid theme is auto-detected from the
active palette via get_mermaid_theme().
render_kv_grid(items)Key-value card grid layout. items is a list of dicts:
| Key | Type | Description |
|---|---|---|
label |
str | Label text |
value |
str | Value text or HTML |
span |
bool | If True, the item spans full width |
HTML templates use .replace() substitution (not .format()) to
avoid conflicts with { and } characters in embedded JS and CSS
content. Placeholders follow the {{PLACEHOLDER}} convention.
Content that contains literal { or } braces must use HTML
entity encoding ({ / }) when placed inside
<textarea> values to prevent template engine interference.
generateDocPDF() performs the following steps:
Subclass Report and override build_pages():
from ObjReportDocumentation import Report as DocBase
class Report(DocBase):
def get_title(self):
return "My Documentation"
def get_subtitle(self, param1="", param2=""):
return f"Package: {self.get_package()}"
def build_pages(self, param1="", param2="", param3=""):
return [
{
"title": "Getting Started",
"icon": "fa-book",
"badge": "Guide",
"badge_color": "primary",
"sections": self.render_section(
"Overview", "fa-info-circle",
"<p>Welcome to the docs.</p>"
),
},
]
_Server_ttl = REPORT_TTL_DOCUMENTATION # 3600 seconds (1 hr)
All documentation report subclasses inherit a 1-hour Redis cache
TTL. Combined with the companion YAML cache.ttl: 3600, this
ensures that documentation reports are served from cache for up to
one hour between regenerations.
The companion YAML also declares:
cache:
ttl: 3600
This module-level TTL override is read by get_cache_ttl() and
compared with _Server_ttl — the larger value wins.
_skip_process_text Bypass_skip_process_text = True
Documentation reports set this flag to bypass process_text()
entirely during WebServer template rendering. Since documentation
output is fully pre-rendered HTML with no $variable$ or
{command:...} markers, skipping the text processing pipeline
avoids unnecessary overhead.
Documentation reports use get_component_css_link() from ObjCss
instead of embedding component CSS inline. This returns a <link>
tag pointing to /css/components.css, which is served with
Cache-Control and ETag headers. The browser caches the CSS file
independently, reducing the HTML payload and avoiding redundant CSS
downloads.