Scope of the proposal
Other
Most impacted component
Documentation
Problem statement and motivation
The BioPAL documentation site was migrated to Sphinx using MyST (Markdown) as the primary markup language. This was a deliberate choice for the initial migration: the previous public site was already in Markdown, and MyST made the pilot easier to iterate on and revert if needed.
ESA stakeholders have since reviewed the approach and pointed out that reStructuredText (RST) is the native markup for Sphinx and is preferred for complex technical documents such as ATBDs. The ESA ADPM (Algorithm Documentation and Publication Manual) also recommends RST for document format (§2.4).
Today, the entire published site including the L2 AGB ATBD, contributing guides, tutorials, and hub pages is authored in Markdown with MyST-specific syntax (:::, {tab-set}, {dropdown}, {numref}, dollar-math, custom directives, etc.). Maintaining two conventions (MyST now, RST expected for future ATBDs) creates:
Governance friction with ESA documentation requirements
Contributor confusion (documentation-standards.md currently allows both Markdown and RST)
Higher conversion cost over time as more ATBDs and SUMs are migrated from PDF
Aligning on RST now while the site is still young reduces long-term drift and matches practices used in comparable ESA / scientific Sphinx projects.
Proposed solution
Migrate Sphinx documentation sources from .md (MyST) to .rst (reStructuredText) in phased, reviewable steps, section by section.
Phase 1 Foundation and ATBD (highest priority)
- Add RST authoring guidelines to documentation-standards.md (RST becomes the required format for new standalone docs; Markdown deprecated).
- Convert the Science Guide / ATBD L2 AGB chapter (docs/science-guide/atbd-l2-agb/*.md) to .rst, preserving:
- numbered equations and cross-references
- figures and {numref}-style references
- sidebar TOC and ATBD-specific extensions (atbd-sidebar-toc, logo banner, PDF export)
- Update index / toctree entries to reference .rst paths.
- Validate make html and make atbd-pdf on CI.
Phase 2 Tutorials and user-facing guides
Convert docs/tutorials/ and docs/getting-started/, docs/user-guide/ including MyST constructs (tab-set, admonitions, dropdowns) to RST / sphinx-design equivalents.
Phase 3 Contributing, governance, communication, licensing
Convert remaining hub and process pages (docs/contributing/, docs/governance/, docs/communication/, docs/about/).
Phase 4 Cleanup
- Remove myst_parser and MyST-specific conf.py settings once no .md Sphinx sources remain.
- Update Edit-on-GitHub links (already configured for .rst in conf.py).
- Exclude or relocate non-Sphinx Markdown (e.g. Open_Source_BIOMASS_v2_slides_spec.md, tutorial README.md bundles) from the migration scope if they are not rendered.
Alternatives considered
No response
Expected impact
No change on backward compatibility
Additional context
No response
Pre-submission checklist
Scope of the proposal
Other
Most impacted component
Documentation
Problem statement and motivation
The BioPAL documentation site was migrated to Sphinx using MyST (Markdown) as the primary markup language. This was a deliberate choice for the initial migration: the previous public site was already in Markdown, and MyST made the pilot easier to iterate on and revert if needed.
ESA stakeholders have since reviewed the approach and pointed out that reStructuredText (RST) is the native markup for Sphinx and is preferred for complex technical documents such as ATBDs. The ESA ADPM (Algorithm Documentation and Publication Manual) also recommends RST for document format (§2.4).
Today, the entire published site including the L2 AGB ATBD, contributing guides, tutorials, and hub pages is authored in Markdown with MyST-specific syntax (:::, {tab-set}, {dropdown}, {numref}, dollar-math, custom directives, etc.). Maintaining two conventions (MyST now, RST expected for future ATBDs) creates:
Governance friction with ESA documentation requirements
Contributor confusion (documentation-standards.md currently allows both Markdown and RST)
Higher conversion cost over time as more ATBDs and SUMs are migrated from PDF
Aligning on RST now while the site is still young reduces long-term drift and matches practices used in comparable ESA / scientific Sphinx projects.
Proposed solution
Migrate Sphinx documentation sources from .md (MyST) to .rst (reStructuredText) in phased, reviewable steps, section by section.
Phase 1 Foundation and ATBD (highest priority)
Phase 2 Tutorials and user-facing guides
Convert docs/tutorials/ and docs/getting-started/, docs/user-guide/ including MyST constructs (tab-set, admonitions, dropdowns) to RST / sphinx-design equivalents.
Phase 3 Contributing, governance, communication, licensing
Convert remaining hub and process pages (docs/contributing/, docs/governance/, docs/communication/, docs/about/).
Phase 4 Cleanup
Alternatives considered
No response
Expected impact
No change on backward compatibility
Additional context
No response
Pre-submission checklist