mkdocs + zensical

[egenn]

No description provided.

[gemini-code-assist]

Code Review

This pull request introduces documentation for the rtemis-a3 project, including API references and a quick start guide. It adds configuration files for MkDocs and Zensical and updates project dependencies accordingly. Feedback was provided regarding inconsistencies between the MkDocs and Zensical configuration files, specifically concerning site metadata and navigation settings.

[gemini-code-assist]

The mkdocs.yml configuration is inconsistent with zensical.toml. Specifically, the site_name differs (rtemis_a3 vs rtemis-a3), and it lacks the nav, site_description, and site_author fields defined in the Zensical configuration. Keeping these in sync ensures a consistent documentation experience regardless of which tool is used for building. Additionally, rtemis-a3 matches the project name in pyproject.toml.

site_name: rtemis-a3
site_description: Python implementation of the A3 amino acid annotation format.
site_author: E.D. Gennatas

nav:
  - Home: index.md
  - API Reference: api.md

[Copilot]

Pull request overview

This PR introduces documentation tooling for the python/rtemis_a3 package, adding MkDocs + mkdocstrings setup alongside a Zensical configuration and new docs pages.

Changes:

• Added MkDocs configuration (mkdocs.yml) with mkdocstrings Python handler settings.
• Added Zensical configuration (zensical.toml) including navigation and mkdocstrings handler settings.
• Added initial documentation pages (docs/index.md, docs/api.md) and updated Python dev dependencies / lockfile to include doc tooling.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/rtemis_a3/zensical.toml	Adds Zensical site configuration, nav, and mkdocstrings handler config.
python/rtemis_a3/mkdocs.yml	Adds MkDocs config enabling mkdocstrings for Python API docs.
python/rtemis_a3/docs/index.md	Adds package overview and usage documentation landing page.
python/rtemis_a3/docs/api.md	Adds mkdocstrings directives for generating API reference pages.
python/rtemis_a3/pyproject.toml	Adds doc tooling (mkdocstrings-python, zensical) to dev dependency group.
python/rtemis_a3/uv.lock	Locks new documentation-related dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

site_name here uses rtemis_a3 (underscore), but the project/package name and the docs content use rtemis-a3 (hyphen). This will make the rendered site header/title inconsistent; consider aligning the MkDocs site_name with the canonical project name used in pyproject.toml and docs/index.md.

Suggested change

	site_name: rtemis_a3
	site_name: rtemis-a3

[Copilot]

docs/index.md appears to duplicate the existing README.md content in this package (and also python/README.md). Keeping multiple copies of the same introductory text tends to drift over time; consider reusing a single source (e.g., include/redirect the README into MkDocs) so updates only need to be made in one place.

Suggested change

	Python implementation of the **Amino Acid Annotation (A3)** format —
	a structured JSON format for amino acid sequences with site, region, PTM,
	processing, and variant annotations.
	Part of the [rtemis-org/a3](https://github.com/rtemis-org/a3) monorepo,
	which provides A3 implementations in Python, TypeScript, R, Julia, and Rust.
	## Installation
	```bash
	pip install rtemis-a3
	# or with uv
	uv add rtemis-a3
	```
	## Quick Start
	```python
	from rtemis.a3 import create_a3
	a3 = create_a3(
	"MKTAYIAKQR",
	site={
	"Active site": {"index": [3, 5], "type": "activeSite"},
	},
	region={
	"Repeat 1": {"index": [[1, 4]], "type": ""},
	},
	ptm={
	"Phosphorylation": {"index": [7], "type": ""},
	},
	variant=[{"position": 3, "from": "K", "to": "R"}],
	metadata={
	"uniprot_id": "P12345",
	"description": "Example protein",
	"organism": "Homo sapiens",
	},
	)
	len(a3.sequence) # 10
	```
	## Parsing JSON
	```python
	from rtemis.a3 import a3_from_json, A3ValidationError, A3ParseError
	try:
	a3 = a3_from_json(json_string)
	except A3ValidationError as e:
	print(e.errors) # list of Pydantic error dicts with field paths
	except A3ParseError as e:
	print(e) # malformed JSON
	```
	## File I/O
	```python
	from rtemis.a3 import read_a3json, write_a3json
	This is the Python implementation of the **Amino Acid Annotation (A3)** format —
	a structured JSON format for amino acid sequences with site, region, PTM,
	processing, and variant annotations.
	Part of the [rtemis-org/a3](https://github.com/rtemis-org/a3) monorepo,
	which provides A3 implementations in Python, TypeScript, R, Julia, and Rust.
	## Documentation entry point
	To avoid keeping multiple copies of the same introductory text in sync, the
	canonical introduction, installation instructions, and quick-start examples
	for the Python package are maintained in:
	- The monorepo root [README](../../README.md)
	- The Python package [README](../README.md)
	Please refer to those documents for:
	- Project overview and A3 format description
	- Installation instructions (`pip`, `uv`, etc.)
	- Quick-start examples for creating and parsing A3 JSON
	- File I/O helpers and error handling
	This `docs/index.md` file serves as the landing page for the generated
	documentation site and intentionally links to a single canonical source for
	the introductory material to prevent documentation drift.

[Copilot]

This repository now has two documentation config entry points (mkdocs.yml and zensical.toml) that both define site/plugin settings, and they currently disagree on the site name (rtemis-a3 here vs rtemis_a3 in mkdocs.yml). If both tools are meant to be supported, consider ensuring shared settings (site name, mkdocstrings handler paths/options, nav) are consistent to avoid confusing/incorrect builds.

[Copilot]

The repo’s Python CI workflow currently runs lint/typecheck/tests but does not build the documentation site. Since this PR adds MkDocs/Zensical configuration and mkdocstrings directives, consider adding a CI step to at least run a docs build (or a mkdocstrings render check) so doc generation failures are caught early.