Metadata-Version: 2.4
Name: py-teststand-autodoc
Version: 0.2.1
Summary: Automated documentation generator for National Instruments TestStand™ sequence files
Project-URL: Homepage, https://github.com/TheDomcio/py-teststand-autodoc
Project-URL: Repository, https://github.com/TheDomcio/py-teststand-autodoc
Project-URL: Issues, https://github.com/TheDomcio/py-teststand-autodoc/issues
Project-URL: Bug Reports, https://github.com/TheDomcio/py-teststand-autodoc/issues
Project-URL: Source Code, https://github.com/TheDomcio/py-teststand-autodoc
Author: Dominik Rajchel
License: MIT License
        
        Copyright (c) 2026 Dominik Rajchel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: autodoc,automatic-documentation,automation,com,documentation,markdown,national-instruments,ni,python,pywin32,test-automation,teststand,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: py-teststand>=0.2.3
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyrefly>=1.1.0
Provides-Extra: pdf
Requires-Dist: markdown>=3.5; extra == 'pdf'
Requires-Dist: playwright>=1.40; extra == 'pdf'
Requires-Dist: zensical>=0.0.45; extra == 'pdf'
Description-Content-Type: text/markdown

# py-teststand-autodoc

[![PyPI version](https://img.shields.io/pypi/v/py-teststand-autodoc.svg)](https://pypi.org/project/py-teststand-autodoc/)
[![Python versions](https://img.shields.io/pypi/pyversions/py-teststand-autodoc.svg)](https://pypi.org/project/py-teststand-autodoc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![OS](https://img.shields.io/badge/OS-Windows-0078D4.svg?logo=windows)](https://www.microsoft.com/windows)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/badge/uv-managed-black?logo=uv)](https://github.com/astral-sh/uv)
[![ty](https://img.shields.io/badge/ty-checked-blue?logo=python)](https://github.com/astral-sh/ty)
[![pyrefly](https://img.shields.io/badge/pyrefly-checked-blue?logo=python)](https://pyrefly.org)
[![TestStand 2016-2026](https://img.shields.io/badge/TestStand-2016--2026-orange.svg)](https://www.ni.com/docs/en-US/bundle/teststand-api-reference/page/tshelp/teststand-api-reference.html)
[![Downloads](https://static.pepy.tech/badge/py-teststand-autodoc)](https://pepy.tech/projects/py-teststand-autodoc)

`py-teststand-autodoc` is an automated rich documentation generator from National Instruments TestStand™ sequence files.

## Table of contents

- [py-teststand-autodoc](#py-teststand-autodoc)
  - [Table of contents](#table-of-contents)
  - [📖 Overview](#-overview)
  - [⚠️Transparency](#️transparency)
  - [🔒 Offline Capability](#-offline-capability)
  - [🚧 Project Status](#-project-status)
    - [🤖 AI-Assisted Development](#-ai-assisted-development)
  - [🚀 Installation](#-installation)
    - [⚡ Global installation](#-global-installation)
    - [📦 Direct execution](#-direct-execution)
  - [💻 CLI usage](#-cli-usage)
    - [⚙️ Generate report from sequence](#️-generate-report-from-sequence)
      - [🎨 Custom CSS](#-custom-css)
    - [📂 Examples](#-examples)
  - [🔗 Compatibility](#-compatibility)
    - [🖥️ TestStand™ \& Environment](#️-teststand--environment)
    - [🌐 Static Site Generators](#-static-site-generators)
  - [🧰 Technical stack](#-technical-stack)
  - [⚖️ Legal](#️-legal)
  - [📄 License](#-license)

---

## 📖 Overview

This project was inspired by [Wovalab Antidoc Add-on for TestStand](https://www.vipm.io/package/wovalab_lib_antidoc_add_on_teststand/), which is built for the
LabVIEW-TestStand ecosystem, because I missed option to easly integrate with Markdown static site generators like
mentioned in [Static Site Generators](#-static-site-generators) and easier integration with actual Python-based tooling.

It can be used in two ways:

1. As a CLI tool
2. As a Python library (via API - see examples)

---

## ⚠️Transparency

This generator does **not** reverse-engineer or natively parse `.seq` files:
uses my other [py-teststand](https://github.com/TheDomcio/py-teststand) project to interact with TestStand™ COM API.
This means you need a valid TestStand™ installation and a proper [TestStand™ License](https://www.ni.com/docs/en-US/bundle/teststand/page/teststand-licensing-options.html) on the machine running the code.

## 🔒 Offline Capability

**100% Offline Rendering**: To address privacy concerns and support offline environments, all PDF and Markdown generation is performed strictly locally.

- **Diagrams**: Mermaid.js diagrams are rendered entirely client-side using a bundled [`mermaid.min.js`](https://cdn.jsdelivr.net/npm/mermaid@11.15.0/dist/mermaid.min.js_ (stored in the package assets) driving a local headless browser session via Playwright.
- **Fonts**: The PDF styling uses bundled [`UbuntuNerdFont-Regular`](https://www.nerdfonts.com/) and standard pre-installed Windows system fonts (such as `Segoe UI` for text and `Cascadia Code` / `Consolas` for code elements).

## 🚧 Project Status

This is a hobby project, maintained on a best-effort basis and **not** yet
under active full-time development ahead of the first release. There is no fixed release
schedule or formal support, but feel free to get in touch.

> [!NOTE]
> **Workspaces not currently supported:** `py-teststand-autodoc` currently processes individual sequence files (`.seq`). Full workspace (`.tsw`) support is not yet implemented.

Treat it as experimental: wrapper behaviour may change between releases without notice
(like error catching or high level imports).

If you hit a bug or unexpected behavior, open an issue with a reproducible case. That is the
best way to get it fixed.

For now i prefer lightweight tags based releases (i protected them in repository settings)
instead of fully described ones until reach 1.0.0 release.

### 🤖 AI-Assisted Development

This project leverages Large Language Models (LLMs) to assist with:

- **Codebase audits** and refactoring.
- **Test coverage analysis** and generation.
- **Documentation drafting**.

This is an independent community project. These AI tools are used to optimize
productivity and are **not** an official component of the project, nor do they integrate
with or replace the official
[NIGEL™ AI Advisor](https://www.ni.com/en/support/software-support/nigel-ai.html)
provided by National Instruments. All generated code is manually reviewed by the
maintainer to ensure it meets the project's quality standards.

---

## 🚀 Installation

Install `py-teststand-autodoc` using `uv`.

### ⚡ Global installation

Install the tool globally to use its CLI commands:

```powershell
uv tool install py-teststand-autodoc
```

For PDF support, include the `pdf` extra:

```powershell
uv tool install py-teststand-autodoc[pdf]
```

> ℹ️ PDF generation uses Playwright to drive a headless Chromium browser (Windows 10+ system Edge by default), therefore no separate browser download is required.

### 📦 Direct execution

Run the tool without installing it globally by using `uvx`:

```powershell
uvx py-teststand-autodoc <input_sequence.seq> -o <output_report.md>
```

To generate a PDF directly, include the `pdf` dependency:

```powershell
uvx --with "py-teststand-autodoc[pdf]" py-teststand-autodoc <input_sequence.seq> -o <output_report.md> --pdf
```

---

## 💻 CLI usage

Generate reports using the `py-teststand-autodoc` and `py-teststand-autodoc-pdf` commands.

### ⚙️ Generate report from sequence

```powershell
py-teststand-autodoc <input_sequence.seq> -o <output_report.md> [options]
```

Options:

- `--profile {engineer,business,station}`: Documentation profile (default: `engineer`). The `station` profile generates a standalone station report with station options, station globals, and search directories.
- `--ignore-skipped`: Omit skipped steps.
- `--models`: Include process models.
- `--batch`: Treat input as a directory and recursively convert all `.seq` files inside it.
- `--variable-scope {Locals,Parameters,FileGlobals,StationGlobals}`: Variable scopes for the appendix.
- `--station`: Include station options.
- `--types`: Include custom types.
- `--types-all`: Include all custom types, not just those attached to the file.
- `--file-custom-data-types`: List custom data types defined in the file.
- `--estimate-software-delays`: Sum Wait expressions to estimate minimum software delays.
- `--detailed-popup-messages`: Include MessagePopup step details in Mermaid diagrams.
- `--author <name>`: Author name for the header (default: `Jan Kowalski`).
- `--company <name>`: Company name for the header (default: `Yesterday Future Company`).
- `--email <email>`: Author email for the header.
- `--version <version>`: Document version for the header.
- `--pdf`: Also render a PDF next to the output file via headless browser.
- `--custom-css <path>`: Path to a custom CSS file to inject into PDF rendering (can override accent color).
- `--browser {msedge,chrome,chromium}`: Chromium channel for PDF rendering (default: `msedge`).

#### 🎨 Custom CSS

The default PDF stylesheet is bundled at `src/py_teststand_autodoc/rendering/pdf.css`.

### 📂 Examples

By default, the `engineer` profile generates all [potentially] useful data (process models, variables by their scope, station options, templates, types) and uses the extended Markdown syntax automatically:

```powershell
# Generates a comprehensive engineering report with all data included
py-teststand-autodoc <input_sequence.seq> -o <output_report.md>
```

The `examples/` directory contains sample scripts for the CLI and API usage. Check them out to learn how to integrate `py-teststand-autodoc` into your own scripts!

```text
examples/
├── cli/
│   ├── run_all.bat
│   └── run_station.bat
└── api/
    ├── basic_generation.py
    ├── business_profile.py
    ├── extended_metadata.py
    ├── pdf_rendering.py
    ├── full.py
    ├── batch_workspace_conversion.py
    └── station.py
```

- [cli/run_all.bat](examples/cli/run_all.bat): Runs the CLI with different option combinations (including `--author` and `--profile business`).
- [cli/run_station.bat](examples/cli/run_station.bat): Generates a standalone station options report.
- [api/basic_generation.py](examples/api/basic_generation.py): Shows how to use the Extractor for default markdown.
- [api/business_profile.py](examples/api/business_profile.py): Shows how to generate business logic reports.
- [api/extended_metadata.py](examples/api/extended_metadata.py): Shows how to programmatically pass author, version, and revision metadata.
- [api/pdf_rendering.py](examples/api/pdf_rendering.py): Shows how to programmatically generate PDFs.
- [api/full.py](examples/api/full.py): Demonstrates all `generate_documentation` parameters in one call.
- [api/batch_workspace_conversion.py](examples/api/batch_workspace_conversion.py): Shows how to batch convert entire directories.
- [api/station.py](examples/api/station.py): Shows how to generate a station options report via API.

---

## 🔗 Compatibility

### 🖥️ TestStand™ & Environment

| Component  | Versions     |
|------------|--------------|
| Windows    | 10+          |
| Python     | 3.11 to 3.14 |
| TestStand™ | 2016 to 2026 |

Older TestStand™ engine versions may also work if the underlying COM interfaces have not changed, but they are not explicitly tested.

### 🌐 Static Site Generators

The generated Markdown output is strictly tested and validated for full compatibility with modern static site generators like:

- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**
- **[Zensical](https://zensical.org/)**

> Additional Markdown validation using [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)
---

## 🧰 Technical stack

| Tool                                          | Purpose                                      |
|-----------------------------------------------|----------------------------------------------|
| **[uv](https://github.com/astral-sh/uv)**     | Python package and project manager           |
| **[ty](https://github.com/astral-sh/ty)**     | Static type checker for interface validation |
| **[ruff](https://github.com/astral-sh/ruff)** | Linter and code formatter                    |
| **[pyrefly](https://pyrefly.org)**            | Static type checker                          |
| **[pytest](https://pytest.org/)**             | Unit and integration test runner             |
| **[Playwright](https://playwright.dev/)**     | Headless Chromium browser for PDF rendering  |

---

## ⚖️ Legal

TestStand™ is a registered trademark of
[National Instruments Corporation](https://www.ni.com). Refer to
[NI's TestStand™ licensing options](https://www.ni.com/en/shop/teststand.html) for
information on required licenses to operate the TestStand™ engine.

`py-teststand-autodoc` is an independent community project and is not affiliated with, endorsed
by, or maintained by National Instruments or its parent company
[Emerson](https://www.emerson.com). References to the TestStand™ API are made
solely for interoperability purposes.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file and [src/py_teststand_autodoc/assets/LICENSE](src/py_teststand_autodoc/assets/LICENSE-3RD-PARTY.txt).
