Metadata-Version: 2.4
Name: oodocs
Version: 1.3.0
Summary: Object-oriented documentation toolkit for authoring DOCX, PDF, and HTML documents from Python object trees.
Author: OODocs contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Gonie-Gonie/oo-docs
Project-URL: Repository, https://github.com/Gonie-Gonie/oo-docs
Project-URL: Documentation, https://github.com/Gonie-Gonie/oo-docs#readme
Project-URL: Issues, https://github.com/Gonie-Gonie/oo-docs/issues
Keywords: object-oriented documentation,document generation,pdf,docx,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Text Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: Pygments>=2.18.0
Requires-Dist: pypdf>=5.4.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: reportlab>=4.2.5
Provides-Extra: apidoc
Requires-Dist: griffe>=1.0; extra == "apidoc"
Requires-Dist: docstring-parser>=0.16; extra == "apidoc"
Provides-Extra: integrations
Requires-Dist: PyYAML>=6.0.0; extra == "integrations"
Requires-Dist: pydantic>=1.10.0; extra == "integrations"
Provides-Extra: bibtex
Requires-Dist: bibtexparser>=1.4.0; extra == "bibtex"
Provides-Extra: engineering
Provides-Extra: pint
Requires-Dist: Pint>=0.24.0; extra == "pint"
Provides-Extra: sympy
Requires-Dist: sympy>=1.13.0; extra == "sympy"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.10.0; extra == "examples"
Requires-Dist: pandas>=2.3.0; extra == "examples"
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: docstring-parser>=0.16; extra == "dev"
Requires-Dist: griffe>=1.0; extra == "dev"
Requires-Dist: PyYAML>=6.0.0; extra == "dev"
Requires-Dist: matplotlib>=3.10.0; extra == "dev"
Requires-Dist: pandas>=2.3.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: setuptools-scm>=8.0.1; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# oodocs

OODocs is an Object-Oriented Documentation Tool: a Python-first toolkit for
building structured documents as ordinary Python objects and rendering the same
source to DOCX, PDF, and HTML.

It is useful when reports, manuals, API references, manuscripts, or release
documents already live near Python data, figures, and scripts. Instead of
treating a document as a string template, OODocs keeps the source of record as a
typed object tree.

## Install

```bash
pip install oodocs
```

OODocs requires Python 3.11 or later.

Optional extras are available for focused workflows:

```bash
pip install "oodocs[examples]"
pip install "oodocs[integrations]"
pip install "oodocs[bibtex]"
pip install "oodocs[pint]"
pip install "oodocs[sympy]"
pip install "oodocs[apidoc]"
```

- `examples` installs dependencies used by the bundled example scripts, such as
  matplotlib and pandas.
- `integrations` installs PyYAML and Pydantic support for their optional
  collectors.
- `bibtex` installs the optional `bibtexparser` backend; the built-in parser
  remains available without it.
- `pint` and `sympy` install only their respective integration bridges.
- `apidoc` installs API collection and docstring parsing dependencies.

Core engineering presentation objects such as `NumberFormat` and `Quantity`
need no optional dependency.

## Quick Start

```python
from oodocs import Chapter, Document, DocumentMetadata, DocumentSettings, Paragraph, Section, bold

report = Document(
    "Hello oodocs",
    Chapter(
        "Getting Started",
        Section(
            "Overview",
            Paragraph(
                "This document was defined with ",
                bold("Python objects"),
                ".",
            ),
        ),
    ),
    settings=DocumentSettings(metadata=DocumentMetadata(author="OODocs")),
)

report.save("artifacts/hello.docx")
report.save("artifacts/hello.pdf")
report.save("artifacts/hello.html")
```

`Document.save(...)` chooses the renderer from the file extension. Use
`save_all(...)` when a workflow normally needs DOCX, PDF, and HTML together:

```python
outputs = report.save_all("artifacts")
print(outputs["docx"], outputs["pdf"], outputs["html"])
```

## Command Line

The package installs an `oodocs` command for common build and validation tasks:

```bash
oodocs build report.py --out artifacts
oodocs build README.md --outputs docx,pdf,html --out artifacts
oodocs build notebook.ipynb --outputs pdf --out artifacts
oodocs validate report.py
```

Python sources can expose a `Document` as `document`, `doc`, or `report`, or a
zero-argument factory such as `build_document()`. Markdown and notebook sources
are imported through the same parser APIs available from Python.
Because a Python source is imported during discovery, build only trusted Python
files and keep command execution behind an `if __name__ == "__main__"` guard.

## What You Can Build

- DOCX, PDF, and HTML documents from one Python object tree
- document-level page layout for page size, margins, and portrait/landscape
  orientation
- authored prose, headings, lists, equations, code blocks, boxes, tables, and
  figures
- captioned tables and figures with automatic numbering and cross-references
- explicit cover/front/main/back matter plus plain object links for unnumbered
  targets
- description lists, schema and CLI reference models, per-line equation
  references, quantities, and multi-document suites
- report panels and reusable visual styles that stay editable in Word
- document comments, footnotes, hyperlinks, citations, and generated references
- Markdown and Jupyter notebook imports that become editable OODocs blocks
- API reference material from Python packages, modules, source trees, and
  docstrings through `oodocs.apidoc`
- release and audit documents from generic metadata models, explicit
  `oodocs.integrations`, and caller-configured `oodocs.evidence` reports

## API Documentation Workflows

Install the `apidoc` extra to collect public Python API objects and render them
as ordinary OODocs content:

```python
from oodocs import Chapter, Document, Paragraph
from oodocs.apidoc import collect_api

api = collect_api("oodocs", public_policy="__all__")
classes = api.select_objects(kind="class", module_prefix="oodocs.components")

doc = Document(
    "Selected API Notes",
    Chapter(
        "Important Classes",
        Paragraph("This chapter is assembled from parsed API objects."),
        *[obj.to_section(level=2, presentation="manual") for obj in classes[:5]],
    ),
)

doc.save_all("artifacts/api-notes")
```

Repository-level API reference builds can also be configured in `pyproject.toml`
and rendered with `ApiHelpBookConfig.from_pyproject(".").save_all(".")`.

## Upgrading from 1.x

Version 1.3 removes `oodocs.adapters`; import external collectors from
`oodocs.integrations.*`. Replace `Equation.from_sympy(...)` with
`oodocs.integrations.sympy.equation_from_sympy(...)`, and import schema, CLI,
engineering, evidence, and suite models from their focused namespaces. See the
[v1.3 migration guide](https://github.com/Gonie-Gonie/oo-docs/blob/main/docs/migration-v1.3.md).

## Links

- Repository: https://github.com/Gonie-Gonie/oo-docs
- Issues: https://github.com/Gonie-Gonie/oo-docs/issues
- License: MIT
