Metadata-Version: 2.4
Name: apograph-templates
Version: 0.1.1
Summary: Install verified Apograph LaTeX and Typst template artifacts.
Author: Elia Innocenti
License-Expression: MIT
Project-URL: Homepage, https://github.com/eliainnocenti/apograph
Project-URL: Repository, https://github.com/eliainnocenti/apograph
Project-URL: Issues, https://github.com/eliainnocenti/apograph/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Apograph

> A curated collection and release system for self-contained LaTeX and Typst
> starter projects.

[![Compile Templates](https://github.com/eliainnocenti/apograph/actions/workflows/compile.yml/badge.svg)](https://github.com/eliainnocenti/apograph/actions/workflows/compile.yml)
[![PyPI](https://img.shields.io/pypi/v/apograph-templates.svg)](https://pypi.org/project/apograph-templates/)
[![License: MIT](https://img.shields.io/badge/original_tooling-MIT-blue.svg)](LICENSE)

## Current release

Apograph v0.2.0 contains two tested, unofficial PoliTo beta templates: a Beamer
presentation starter/showcase and a Bachelor's/Master's thesis starter. Neither
is endorsed by Politecnico di Torino, and institution logos/backgrounds are not
redistributed. Other template ideas remain private inventory until they pass the
same publication gates.

Use the actions in the catalog below rather than copying a source directory from
the repository. Each release ZIP is self-contained and is the exact artifact
compiled by CI.

## Available templates

<!-- BEGIN GENERATED:PUBLIC_TEMPLATES -->

| Template | Purpose | Institution | Format | Status | ID | Actions |
|---|---|---|---|---|---|---|
| PoliTo Beamer Presentation | presentation | Politecnico di Torino (unofficial) | latex | beta | `presentation-beamer-polito-latex` | [Preview](https://github.com/eliainnocenti/apograph/releases/download/v0.2.0/presentation-beamer-polito-latex.preview.pdf) · [Download ZIP](https://github.com/eliainnocenti/apograph/releases/download/v0.2.0/presentation-beamer-polito-latex.zip) · [Open in Overleaf](https://www.overleaf.com/docs?snip_uri=https%3A%2F%2Fgithub.com%2Feliainnocenti%2Fapograph%2Freleases%2Fdownload%2Fv0.2.0%2Fpresentation-beamer-polito-latex.zip) |
| PoliTo Thesis | thesis | Politecnico di Torino (unofficial) | latex | beta | `thesis-polito-latex` | [Download ZIP](https://github.com/eliainnocenti/apograph/releases/download/v0.2.0/thesis-polito-latex.zip) · [Open in Overleaf](https://www.overleaf.com/docs?snip_uri=https%3A%2F%2Fgithub.com%2Feliainnocenti%2Fapograph%2Freleases%2Fdownload%2Fv0.2.0%2Fthesis-polito-latex.zip) |

<!-- END GENERATED:PUBLIC_TEMPLATES -->

The table is generated by:

```bash
python3 scripts/catalog.py generate-readme
```

CI checks that it remains synchronized with the catalog.

## Use a template

Choose one of the actions in the public catalog:

- **Preview** opens the PDF produced from the packed showcase.
- **Download ZIP** gives you the complete starter for local tools and VS Code.
- **Open in Overleaf** imports that same versioned ZIP into a new Overleaf
  project; sign-in may be required.

For a local start, extract the ZIP and read its included README. User-facing
metadata lives in `config.tex`; document content lives under `content/` (for
example `content/slides.tex` in the presentation). Then run:

```bash
latexmk -pdf main.tex
```

In VS Code, open the extracted folder and accept the recommended LaTeX Workshop
extension. The artifact supplies a build recipe and keeps generated files under
`out/`. In Overleaf, keep `main.tex` selected as the main document. The browser
workflow requires no repository checkout, CLI installation, custom `TEXINPUTS`,
or asset download.

To verify a local download using its matching sidecar:

```bash
shasum -a 256 -c <template-id>.zip.sha256
```

The public templates are tested with pdfLaTeX in TeX Live 2026 and on Overleaf;
the Beamer template also retains its TeX Live 2025 compatibility record. See the
[v0.2.0 release notes](docs/releases/v0.2.0.md) for known limitations. Report
reproducible problems through
[GitHub Issues](https://github.com/eliainnocenti/apograph/issues).

## Command-line setup

The optional `apograph` client discovers only published releases and installs
the exact catalog-backed ZIP after verifying its SHA-256 digest. Install the
independently versioned client from [PyPI](https://pypi.org/project/apograph-templates/)
with Python 3.10 or newer:

```bash
pipx install apograph-templates
```

Then list, inspect, or create a project:

```bash
apograph list
apograph info thesis-polito-latex
apograph new thesis-polito-latex my-thesis
apograph new presentation-beamer-polito-latex my-slides --version v0.2.0
```

The default is the newest published Apograph release, including prereleases.
Pass `--version` to pin one immutable collection. `apograph new` refuses any
destination that already exists and never rewrites template source. Anonymous
GitHub access is sufficient; `GITHUB_TOKEN` is accepted when users need a higher
API allowance.

For one-off use without a permanent installation:

```bash
pipx run --spec apograph-templates apograph new \
  thesis-polito-latex my-thesis
```

The PyPI distribution name `apograph` belongs to an unrelated project. Install
the distribution `apograph-templates`; its executable is still `apograph`.

## Architecture

Templates are organized primarily by purpose:

```text
templates/<purpose>/<variant>-<format>/
```

`CATALOG.json` is the only authored metadata source. Institution, format,
compiler, status, licensing, provenance, and assets are catalog facets.
Per-template `template.json` manifests are generated only inside release
artifacts.

Shared source modules live under `shared/`. During development, maintainers edit
them once. Release artifacts vendor the exact required modules at ZIP root so a
downloaded template has no runtime dependency on this repository.

See the [maintainer development guide](docs/maintainer/development.md) for the
catalog, authoring, artifact, validation, and release contracts, and the
[roadmap](docs/maintainer/roadmap.md) for active work.

## Maintainer quick start

Requirements for the current LaTeX tooling:

- Python 3;
- TeX Live or MacTeX with `latexmk`;
- Typst later, when the first Typst draft is implemented.

Validate catalog and repository metadata:

```bash
python3 scripts/catalog.py validate
python3 scripts/catalog.py list
python3 scripts/catalog.py generate-readme --check
```

Run all catalog, artifact, and isolated-compile tests:

```bash
python3 -m unittest discover -s tests -v
```

Build and compile the PoliTo beta artifact in an isolated temporary directory:

```bash
python3 scripts/pack.py presentation-beamer-polito-latex
```

This creates a deterministic ZIP, checksum, build report, and packed-source
preview under `build/`. `python3 scripts/preview.py <id>` remains a faster
source-tree convenience and is not the release gate.

## Adding templates

Apograph is currently maintained as a personal curated collection. The public
repository accepts reproducible bug reports through Issues; a third-party
contribution workflow can be added later if routine external submissions become
part of the project. Maintainer rules include:

- new entries start as `draft`;
- adapted work needs upstream provenance and license evidence;
- institution marks need a declared redistribution/trademark policy;
- `official` is reserved for templates endorsed by the represented institution;
- generated metadata and public listings must not be edited by hand.

The full workflow is in the [maintainer development
guide](docs/maintainer/development.md).

## Licensing

Original Apograph tooling is provided under the [MIT License](LICENSE).
Individual templates, adapted themes, and institution assets may have different
or unresolved terms and are governed by their catalog metadata and notices.
Nothing with unresolved redistribution requirements is eligible for public
release.

See [docs/licensing.md](docs/licensing.md) for the current evidence inventory and
open human decisions.
