Metadata-Version: 2.4
Name: theoworks-sphinx-build
Version: 0.1.1
Summary: The TheoWorks Sphinx extension that emits theoworks-schema.json and the optional diagram-image and computed-directive-result manifests
Author: TheoWorks
License-Expression: Apache-2.0
Project-URL: Homepage, https://theoworks.io
Project-URL: Source, https://gitlab.com/theoworks/theoworks
Keywords: sphinx,sphinx-needs,requirements,ASPICE,traceability
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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 :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: extension
Requires-Dist: sphinx>=7.4; extra == "extension"
Requires-Dist: sphinx-needs>=8.1.1; extra == "extension"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: sphinx>=7.4; extra == "dev"
Requires-Dist: sphinx-needs>=8.1.1; extra == "dev"
Requires-Dist: PyYAML; extra == "dev"
Dynamic: license-file

# theoworks-sphinx-build

The [TheoWorks](https://theoworks.io) Sphinx extension that emits
`theoworks-schema.json` and the optional diagram-image and
computed-directive-result manifests. It runs inside a
[sphinx-needs](https://sphinx-needs.readthedocs.io) build and emits exactly
the artifacts that genuinely require an in-build render:

- `theoworks-schema.json` — the RESOLVED `needs_*` metamodel, captured after
 every extension's `setup()` has run (so an extension-registered metamodel,
 e.g. a bundle bringing its own `needs_types`, is recoverable even though it
 never appears as a `conf.py` literal).
- `theoworks-directive-images.json` — the needuml/needsequence
 diagram-image location manifest (only when PlantUML rendered one).
- `theoworks-directive-results.json` — the computed needtable/needlist/
 needextract/needbar/needpie result manifest (only when a computed
 directive occurs).

## Install

```bash
pip install theoworks-sphinx-build
```

## Usage

Add the extension to your project's `conf.py` (after `sphinx_needs`) — note
the **importable module name stays `theoworks_sphinx`**, even though the
PyPI distribution is `theoworks-sphinx-build` (so an existing
`extensions = [..., "theoworks_sphinx"]`, including anything TheoWorks has
already scaffolded for you, keeps working unchanged):

```python
extensions = ["sphinx_needs", "theoworks_sphinx"]
```

Then build as usual:

```bash
sphinx-build -b html docs public
```

If the package is not installed, a TheoWorks-scaffolded `conf.py` degrades
gracefully — the build still succeeds and still produces `needs.json` (the
floor); you only lose the richer previews above.
