[feature] Migrate documentation site source into the repository (Sphinx, GitHub Pages, Edit on GitHub)

[yreyricord]

Scope of the proposal

Other

Most impacted component

Documentation

Problem statement and motivation

The BIOMASS BPS documentation is already published at https://biomass-disc.info/docs and is rich in content (user guide, science guide, governance, contributing).

However, the source of the site is not under version control in this repository. The current setup has three consequences that block the open source story:

• External contributors cannot edit the documentation through the standard pull request workflow. A scientist who spots an error in the science guide, or a developer who notices a stale CLI flag in the user guide, has no way to propose a fix. They have to email a maintainer or open an issue and wait for someone to manually update an external system.
• There is no "Edit on GitHub" link on the published pages, which is the de facto standard for open source documentation (xarray, numpy, pandas, FastAPI all surface it). Without it, the friction to fix a typo is ten minutes; with it, the friction is thirty seconds.
• The documentation is not in sync with the code via PRs. A code change that requires a doc update is invisible to reviewers because the doc lives in a separate system. Reviewers cannot enforce "doc-and-code-in-the-same-PR" without the docs being in the repo.
• The published site itself is fine. The issue is purely about where the source lives: moving it from its current external location into docs/ inside this repository, so the existing site can be redeployed from CI on every merge to develop and contributors can edit it through the same workflow they use for code.

Proposed solution

Migrate the documentation source files into a docs/ directory at the repository root, restructured around the Sphinx framework already in use on the published site, and wire the GitHub Pages deploy. Details:

Source migration:

• Import the existing site source (currently maintained outside this repository) into docs/.
• Preserve the existing section structure (about, getting-started, user-guide, tutorials, science-guide, developer-guide, contributing, governance).
• Keep MyST Markdown as the authoring format (no conversion of content).
• Preserve all existing assets (images, diagrams, logo) under docs/_static/ and docs/_extra_static/.

Theme and configuration:

• docs/conf.py Sphinx + PyData Sphinx Theme + MyST parser + sphinx-design + sphinx-copybutton.
• docs/requirements.txt Sphinx and extensions pinned to the versions currently used in production.
• docs/Makefile local build (make html, make linkcheck).
• Theme overrides (docs/_static/custom.css) preserve the current visual identity, with Blue ACRI #347891 as primary accent.

"Edit on GitHub" wiring:

• html_theme_options in conf.py enables the use_edit_page_button flag of PyData theme.
• Every rendered page now displays an "Edit on GitHub" link in the top-right corner, pointing to the source .md file on develop.
• The link follows the convention used by xarray (https://github.com/BioPAL/BPS/edit/develop/docs/.md).

Build and deploy workflow:

• .github/workflows/docs.yml build on every PR touching docs/ (with -W upgrading warnings to errors), linkcheck on every PR, deploy to GitHub Pages on push to develop.
• GitHub Pages source set to "GitHub Actions" in repository Settings.
• Existing biomass-disc.info/docs URL is kept as the canonical public URL during the transition. CNAME or redirect strategy from biopal.github.io/BPS is handled separately by the maintainers responsible for the biomass-disc.info domain.

README and discovery:

• README.md gets a "Documentation" section pointing to the live site and explaining how to contribute via the Edit on GitHub link.
• The issue template chooser (.github/ISSUE_TEMPLATE/config.yml) already points to the docs site; no change there.

Scientific documentation (ATBD) and Software User Manuals (SUM):
These exist only as PDFs and will not be converted to Markdown in this iteration. They are surfaced as placeholder pages with prominent PDF download links:

• PDFs committed under docs/_static/pdf/ (versioned, deployed with the site).
• One short placeholder page per document under docs/science-guide/atbd-.md and docs/user-guide/sum-.md, containing: a one-sentence scope, the download link, the document version, and a pointer to the Documentation issue template for reporting errors.
• Each placeholder spawns a follow-up [docs] Convert to Markdown issue labelled help-wanted.

Alternatives considered

Wait for the Markdown conversion of every ATBD and SUM before publishing the site: rejected. Multi-month effort, no committed date. The placeholder pattern is a strict superset of the current situation.

Expected impact

Documentation only

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.