[feature] Adopt a NASA APT-inspired ATBD authoring model in the Sphinx documentation

[yreyricord]

Scope of the proposal

Governance or process improvement

Most impacted component

Documentation

Problem statement and motivation

The ATBDs and Software User Manuals for BIOMASS BPS are currently published as PDFs hosted on biomass-disc.info. The Sphinx site links to them via placeholder pages on the Science Guide and User Guide. This works as a stopgap but locks the project into the limitations of PDF-only documentation:

1. The source is not in the repository. External contributors cannot propose fixes, typo corrections, or factual updates through the standard pull request workflow.
2. Content is not searchable, machine-readable, or web-indexed. A scientist looking for "L1 SAR ATBD section 4.2 validation criteria" lands on a 100-page PDF and has to scroll.
3. Each ATBD has its own structure. A reader who knows the AGB ATBD has to relearn where things are in the FH or FD ATBD.
4. References, equations, figures, and citations are duplicated across ATBDs because they live in separate files with no shared bibliography.
5. No connection to code or data. The ATBD does not link to the bps-* package that implements it, nor to validation datasets or auxiliary files.

NASA's IMPACT team has already solved this problem for Earth Observation science with the Algorithm Publication Tool (APT). Their core insight: ATBD content is stored as structured metadata, not as a document. PDFs and HTML pages are rendered on demand from the same source. The APT enforces a single standardised template for every ATBD, exposes them through a centralised repository, links them to data and code, and supports versioning, DOIs, and search.

This issue tracks the adoption of an equivalent model for BIOMASS BPS, leveraging the Sphinx site we already operate.

Proposed solution

Eight changes, sized so they can be picked up progressively rather than as one mega-PR:

1. Create a canonical ATBD template under docs/_templates/atbd_template.md. A single MyST file that every future ATBD migration clones. Section structure inspired by NASA's ESDS-RFC-053 and ESA conventions:

1. Introduction (purpose, scope, applicable and reference documents)
2. Algorithm overview (scientific context, heritage, prior work)
3. Algorithm description (theoretical basis, equations, inputs, outputs, assumptions, limitations)
4. Performance and validation (methodology, results, uncertainties)
5. Implementation (link to bps-* package, auxiliary data, configuration, reference outputs)
6. References
7. Acronyms and glossary
8. Document history and version

2. Define an ATBD frontmatter schema. Every ATBD page starts with structured metadata, equivalent to what APT stores in its database. Example:

---
atbd:
  reference: "BIO-BPS-L1-SAR-ATBD-ARE-010165"
  version: "1.2.4"
  date: "2026-03-27"
  doi: "10.5281/zenodo.XXXXXXX"
  sme_lead: "S. Tebaldini (PoliMi)"
  software_lead: "R. Piantanida (Aresys)"
  bps_packages: [bps-l1_pre_processor, bps-l1_framing_processor, bps-l1_core_processor, bps-l1_processor]
  status: "approved"
  pdf_archive: "/_static/pdf/BPS_L1_SAR_ATBD_v1_2_4.pdf"
---

The same data feeds the existing applicable-documents.md table so the canonical metadata lives in one place.

3. Add sphinxcontrib-bibtex to docs/requirements.txt. Seed docs/references.bib with the BIOMASS canonical references (Quegan 2019, Cazcarra-Bes 2023, Pardini 2024, IERS bulletins, ATBD heritage papers). Every ATBD cites from the same shared bibliography. No duplicated citation strings, automatic numbering.

4. Write docs/contributing/atbd-writing-guide.md. A short one-pager covering MyST conventions for ATBD authors: math blocks, figure embedding, table syntax, units, citation style, glossary entries. Mirrors what APT provides through its authoring UI but as documentation rather than software.

5. Add a make atbd-pdf Sphinx LaTeX builder target. Generates a downloadable PDF per ATBD on demand. The PDF is the same source as the HTML, no double maintenance. CI publishes the PDFs as build artefacts on every release.

6. Standardised "Related resources" admonition at the bottom of every ATBD page. Links the ATBD to its bps-* package, the corresponding Product Format Document, the SUM section, the Zenodo DOI for the algorithm, and the validation dataset. This is APT's "Connect to Related Data via CMR" feature, done with Markdown.

7. Mint Zenodo DOIs per ATBD version. For each tagged ATBD version, a DOI is registered via Zenodo through GitHub releases. Each ATBD page exposes its citation block (BibTeX, formatted citation).

8. Migrate one proof-of-concept ATBD. Port the L1 SAR ATBD (BIO-BPS-L1-SAR-ATBD-ARE-010165) section by section into the template. This is the model we show to ESA and clone for the other ATBDs. Estimated effort: one Scientific Module Expert plus a documentation contributor for two to three weeks.

Alternatives considered

• Keep ATBDs as PDFs only: rejected. Locks out external contributions, blocks search, and prevents linking ATBDs to the code that implements them. PDFs remain available as archival downloads, not as the authoring source.
• Adopt the APT tool itself: rejected. APT is a NASA-hosted SaaS tied to the NASA EOSDIS ecosystem and DAAC submission workflow. It does not fit an ESA-funded open source project. We replicate the Idea, not the tool.
• Use a separate documentation system (Read the Docs, MkDocs, GitBook): rejected. We already operate a Sphinx site with the PyData theme, MyST parser, sphinx-design, and a CI pipeline. Adding a parallel doc system multiplies maintenance cost for no benefit.
• Wait for ESA to mandate a format: rejected. The Sphinx site is the public face of the project; we can adopt the model now and adapt later if ESA requirements emerge.

Expected impact

Dimension	Impact
Backward compatibility	None. ATBDs as PDFs remain available; the new pages add to the documentation.
Authoring experience	Scientific Module Experts edit Markdown locally and propose changes through pull requests like the rest of the project.
Reader experience	ATBDs become searchable, web-indexable, and linkable. Each section has a permalink.
Validation	A first proof-of-concept (L1 SAR ATBD) lets ESA and the SMEs review the format before scaling.
Documentation	The Science Guide stops being a placeholder index of PDFs and becomes the canonical scientific reference.
Dependencies	sphinxcontrib-bibtex added to docs/requirements.txt. No runtime dependency.
Long-term	ATBDs evolve with the code, in the same repository, under the same review process. The Sphinx site replaces biomass-disc.info as the authoritative source over time.

Additional context

No response

Pre-submission checklist

• I have searched existing issues and discussions for a similar proposal.
• I have read the contributing guidelines and the project governance.
• I am available to discuss the design before any implementation starts.