Metadata-Version: 2.4
Name: html-doc
Version: 0.1.0
Summary: Neat plugin for generating HTML documentation from data model definitions.
Author: Per Olav Opdahl
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cognite-neat>=1.0.59
Requires-Dist: openpyxl>=3.0

# html-doc-plugin

NEAT write plugin that generates a self-contained, interactive HTML documentation
file from any loaded NEAT physical data model.

---

## Install

Install in editable mode from the local folder:

    pip install -e path/to/html-doc-plugin

---

## Quick start

### Via the NEAT plugin framework (recommended)

Install the package and NEAT auto-discovers the plugin through the entry-point
cognite.neat.plugin.data_model.file_writers:

    from cognite.neat import NeatSession, get_cognite_client

    client = get_cognite_client('.env')
    neat = NeatSession(client)

    neat.physical_data_model.read.cdf('my_space', 'my_model', 'v1')
    neat.physical_data_model.write.html_doc('docs/model.html')
    # prints: Generated: .../docs/model.html

Optional kwargs: cdm=, idm=, erbose=True.

### Via attach_plugin() (session-aware, legacy helper)

ttach_plugin() monkey-patches the write object and captures the live
NeatSession so CDM and IDM are fetched from CDF automatically:

    from cognite.neat import NeatSession, get_cognite_client
    from html_doc import attach_plugin

    client = get_cognite_client('.env')
    neat = attach_plugin(NeatSession(client))

    neat.physical_data_model.read.cdf('my_space', 'my_model', 'v1')
    neat.physical_data_model.write.html_doc('docs/model.html')
    # prints: Generated: .../docs/model.html

---

## What the plugin generates

The output is a **single self-contained HTML file** that opens in any browser
with no server or extra files needed.

### Header

- **Title**: the data model name from the metadata `name` field.
- **Subtitle**: the canonical CDF identifier in the format
  `space:externalId (version=version)` matching what is stored in CDF.

### Statistics bar

Total view types, properties, relations, and industry domains in the model.

### Domain sections

Views are automatically categorised into industry domains based on ISO 14224,
CFIHOS, OSDU, SAP APM, and ISO 15288 naming conventions, for example
*Activities and Work Management*, *Location and Geography*, and
*Instrumentation and Control*. Each domain section contains one card per view type.

### View type cards

Each card shows:

- Display name, description, and which CDM type it implements (e.g. CogniteAsset).
- Own and inherited property counts.
- Full property table: own properties plus inherited properties with source indicated.
- Collapsible by default; expand individually or with Expand All / Collapse All.

### ER diagrams - five levels

| Level | Name | What it shows |
|-------|------|---------------|
| 1 | Domain Overview | All domain entities grouped by cluster, coloured by domain |
| 2 | Entity Focus | One diagram per entity: the entity, all direct incoming/outgoing relations, and its CDM parent |
| 3 | Domain Relationship Map | All domain entities and every data relation between them, no CDM nodes |
| 4 | Full Architecture with CDM | Domain entities plus the Cognite Core Data Model foundation they extend |
| 5 | All Relations incl. CDM Implements | Every domain entity, every data relation, and every implements arrow to a CDM type |

**Diagram interactivity:**

- Pan and zoom inside every diagram.
- Pop out any diagram into a full-screen overlay.
- Click any entity box to open its detail card.
- Hover over any entity box to highlight all connected relation lines;
  other lines are dimmed. Works in both inline and pop-out views.

### Search and theming

- A live search bar filters view cards across all domains instantly.
- A toggle in the header switches between dark and light mode; all diagrams
  re-render with appropriate colours.

---

## How CDM context is resolved

The Cognite Core Data Model (CDM) is needed for Level 4 and Level 5 diagrams,
the Entity Hierarchy, and for the implements annotation on each view card.
The plugin resolves it in this priority order:

**1. Explicit override**

Pass `cdm=path/to/CogniteCore.yaml` to use a specific file and skip all auto-detection.

**2. Live fetch from CDF (default, recommended)**

A separate, temporary NeatSession is created using the same CDF credentials.
It reads `cdf_cdm:CogniteCore v1` from CDF and exports it to a temporary YAML
file that is deleted after the HTML is written.
The loaded model in the calling session is never modified.
If the fetch fails for any reason (no connectivity, no permission) the plugin
silently falls through to the next option.

**3. Bundled fallback**

A copy of `CogniteCore.yaml` is shipped inside the plugin package and is used
when neither an explicit path nor a live fetch is available.

Note: the bundled fallback may lag behind the live CDF version.
Update it by copying a fresh `CogniteCore.yaml` into the `html_doc/` folder
and reinstalling with `pip install -e .`

---

## How IDM context is resolved

The Cognite Industrial Data Model (IDM, `CogniteProcessIndustries`) adds
industry-specific entity types on top of CDM and is used to populate the
*IDM Industry Types* tab and the Entity Hierarchy.
The plugin resolves it in the same priority order as CDM:

**1. Explicit override**

Pass `idm=path/to/CogniteProcessIndustries.yaml` to use a specific file.

**2. Live fetch from CDF (default, recommended)**

A separate, temporary NeatSession fetches `cdf_idm:CogniteProcessIndustries v1`
from CDF into a temporary YAML that is deleted after generation.

**3. Bundled fallback**

A copy of `CogniteProcessIndustries.yaml` is shipped inside the plugin package.

Note: the bundled fallback may lag behind the live CDF version.
Update it by copying a fresh `CogniteProcessIndustries.yaml` into the `browse_model/`
folder and reinstalling with `pip install -e .`

---

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| io | str or Path | required | Output path for the .html file |
| cdm | str or Path or None | None | Explicit CDM YAML path (`CogniteCore.yaml`), skips auto-fetch |
| idm | str or Path or None | None | Explicit IDM YAML path (`CogniteProcessIndustries.yaml`), skips auto-fetch |
| script_path | str or Path or None | None | Override path to generate_documentation_v7.py |
| verbose | bool | False | Print detailed progress; quiet by default |

---

## How it works internally

### Plugin framework path (HtmlDocPlugin / HtmlDocExporter)

1. NEAT discovers HtmlDocPlugin via the cognite.neat.plugin.data_model.file_writers
   entry-point when the package is installed.
2. When write.html_doc(io, **kwargs) is called, NEAT calls
   HtmlDocPlugin.configure(io=..., **kwargs), which returns a
   HtmlDocExporter instance.
3. NEAT calls HtmlDocExporter.export_to_file(data_model, file_path),
   passing the loaded RequestSchema and the output path.
4. export_to_file converts RequestSchema to a temporary YAML using
   DMSTableYamlExporter, resolves CDM and IDM, and calls
un_generation().
5. All temporary files are deleted.

### Script resolution order for generate_documentation_v7.py

1. script_path= argument
2. NEAT_HTML_DOC_SCRIPT environment variable
3. Bundled copy inside the plugin package (primary)
4. ../NEAT_PROJECTS/ relative to the plugin folder
5. Current working directory
6. C:/neat/NEAT_PROJECTS/ as last resort

---

## Running the generator as a standalone script

`generate_documentation_v7.py` can also be invoked directly from the command
line without installing the plugin or connecting to CDF.  This is useful for
quickly generating docs from local files.

### Usage

    python generate_documentation_v7.py <input_file> [options]

### Arguments

| Argument | Description |
|----------|-------------|
| `input_file` | Path to the NEAT data model file (`.yaml`, `.yml`, or `.xlsx`) |
| `--cdm PATH` | Path to a local `CogniteCore.yaml` (Cognite Core Data Model). If omitted, a bundled copy is used. |
| `--idm PATH` | Path to a local `CogniteProcessIndustries.yaml` (Cognite Industrial Data Model). If omitted, a bundled copy is used. |
| `-o / --output PATH` | Output HTML file path. Defaults to `<input>.html` in the same folder. |

### Examples

Generate docs using only the input model (CDM and IDM resolved from bundled files):

    python generate_documentation_v7.py my_model.yaml

Provide explicit CDM and IDM files:

    python generate_documentation_v7.py my_model.yaml \
        --cdm path/to/CogniteCore.yaml \
        --idm path/to/CogniteProcessIndustries.yaml

Specify a custom output path:

    python generate_documentation_v7.py my_model.xlsx -o docs/my_model.html

On Windows (PowerShell), use `` ` `` for line continuation or write the
command on a single line:

    python generate_documentation_v7.py my_model.yaml --cdm CogniteCore.yaml --idm CogniteProcessIndustries.yaml -o docs/output.html
