docs: add Doxygen API reference to the versioned documentation site

Generate the Doxygen API reference of the core and publish it with each
documentation version, so it is available at /dev/doxygen/,
/latest/doxygen/ and /<X.Y.Z>/doxygen/.

- Add doxygen/Doxyfile covering cores, libraries, system and variants,
  excluding cores/arduino/api, system/Drivers and system/Middlewares.
  Source listings are disabled to keep each published version small.
  __cplusplus and the HAL module macros used as guards are predefined so
  that classes such as HardwareTimer are documented.
- Add an HTML header and version-selector.js: every Doxygen page links
  back to the documentation home of the same version and provides a
  version selector (dev, latest, releases) fed by the mike versions.json.
  When a page does not exist in the selected version, it falls back to
  the Doxygen home page, then to the documentation home page.
- Add docs/hooks/doxygen.py, a MkDocs hook adding the Doxygen output to
  the site, or a placeholder page when it is absent so that documentation
  only builds still pass mkdocs build --strict.
- Build the Doxygen output in docs-check.yml and publish-docs.yml before
  MkDocs, check that it is part of the site, and also trigger both
  workflows on changes to the documented sources.
- Ignore doxygen/** in the Arduino, CMake and PlatformIO build workflows.
- Link the reference from API.md, the home page, the Core Reference
  navigation and README.md.
- Document the Doxygen generation, publication and version selector in
  Documentation-workflow.md.
- Restrict the release tag pattern to a major version below 1000 in
  publish-docs.yml (tag validation and "latest" computation) and in the
  supported boards generator. The legacy date tags 2017.8.31 to
  2018.1.18 matched X.Y.Z and were seen as the highest tag, so "latest"
  and the site default would never have moved to a new release.
- Document in Documentation-workflow.md how the supported boards
  "Next release" labels are resolved from the release tags, and that
  docs/supported-boards/index.md must be regenerated and committed after
  a release tag.

Assisted-by: GitHub Copilot: Claude Sonnet 5.5
Signed-off-by: Frederic Pillon <frederic.pillon@st.com>

Author: fpistm

.github/workflows/Arduino-build.yml

@@ -9,6 +9,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt
@@ -24,6 +25,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt

.github/workflows/Cmake.yml

@@ -10,6 +10,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt
@@ -22,6 +23,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt

.github/workflows/PIO-build.yml

@@ -10,6 +10,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt
@@ -26,6 +27,7 @@ on:
       - '*.json'
       - '**.md'
       - docs/**
+      - doxygen/**
       - mkdocs.yml
       - requirements-docs.txt
       - keywords.txt

.github/workflows/docs-check.yml

@@ -10,6 +10,13 @@ on:
       - boards.txt
       - mkdocs.yml
       - requirements-docs.txt
+      - doxygen/**
+      - cores/**
+      - libraries/**
+      - variants/**
+      - system/**
+      - "!system/Drivers/**"
+      - "!system/Middlewares/**"
       - .github/workflows/docs-check.yml
 
 permissions:
@@ -26,6 +33,16 @@ jobs:
         with:
           python-version: "3.x"
       - run: python -m pip install -r requirements-docs.txt
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install --yes doxygen
+      - name: Build Doxygen API reference
+        run: |
+          STM32_CORE_VERSION=$(sed -n 's/^version=//p' platform.txt)
+          export STM32_CORE_VERSION
+          doxygen doxygen/Doxyfile
+          test -f build/doxygen/index.html
       - run: mkdocs build --strict
+      - name: Check the Doxygen API reference is part of the site
+        run: grep -q 'name="generator" content="Doxygen' site/doxygen/index.html
       - name: Check generated supported boards page is committed
         run: git diff --exit-code -- docs/supported-boards/index.md || { echo "::error::Run 'python docs/hooks/supported_boards.py' and commit docs/supported-boards/index.md"; exit 1; }

.github/workflows/publish-docs.yml

@@ -11,6 +11,13 @@ on:
       - boards.txt
       - mkdocs.yml
       - requirements-docs.txt
+      - doxygen/**
+      - cores/**
+      - libraries/**
+      - variants/**
+      - system/**
+      - "!system/Drivers/**"
+      - "!system/Middlewares/**"
       - .github/workflows/publish-docs.yml
   workflow_dispatch:
 
@@ -33,6 +40,14 @@ jobs:
         with:
           python-version: "3.x"
       - run: python -m pip install -r requirements-docs.txt
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install --yes doxygen
+      - name: Build Doxygen API reference
+        run: |
+          STM32_CORE_VERSION=$(sed -n 's/^version=//p' platform.txt)
+          export STM32_CORE_VERSION
+          doxygen doxygen/Doxyfile
+          test -f build/doxygen/index.html
       - name: Configure Git author
         run: |
           git config user.name "github-actions[bot]"
@@ -68,11 +83,13 @@ jobs:
         env:
           VERSION: ${{ github.ref_name }}
         run: |
-          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+          # Core releases have a major version below 1000: this excludes the
+          # legacy date tags such as 2018.1.18, which would otherwise sort last.
+          if [[ ! "$VERSION" =~ ^[0-9]{1,3}\.[0-9]+\.[0-9]+$ ]]; then
             echo "Unsupported documentation release tag: $VERSION" >&2
             exit 1
           fi
-          latest=$(git tag --list | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
+          latest=$(git tag --list | grep -E '^[0-9]{1,3}\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
           if git ls-remote --exit-code --heads pages gh-pages >/dev/null; then
             git fetch pages gh-pages:gh-pages
           fi

README.md

@@ -16,7 +16,8 @@
 * [Getting Started](https://github.com/stm32duino/Arduino_Core_STM32#getting-started)<br>
 * [Supported boards](docs/supported-boards/index.md)<br>
 * [Troubleshooting](https://github.com/stm32duino/Arduino_Core_STM32#troubleshooting)<br>
-* [Documentation](https://stm32duino.github.io/latest/)
+* [Documentation](https://stm32duino.github.io/latest/)<br>
+* [API reference (Doxygen)](https://stm32duino.github.io/dev/doxygen/)
 
 ## Introduction
 

docs/API.md

@@ -5,6 +5,9 @@
 
 This page documents STM32-specific additions and extensions. For the standard Arduino API, see the [Arduino language reference](https://docs.arduino.cc/language-reference/) and the [ArduinoCore-API documentation](https://github.com/arduino/ArduinoCore-API).
 
+> [!TIP]
+> The source-level reference of the core, generated with Doxygen from the code comments (classes, structures, functions and their parameters), is available in the [Doxygen API reference](doxygen/index.html). It follows the documentation version selected in this site: use the version selector to switch between `dev` and the released versions.
+
 ## Core
 
 This part describes the STM32 core functions.

docs/development/Documentation-workflow.md

@@ -8,7 +8,8 @@ The STM32 core documentation is maintained in the `docs/` directory of the `stm3
 2. Add new pages to the `nav` section in `mkdocs.yml`. The navigation is explicit, so a file that is not listed there will not appear in the sidebar.
 3. Use relative links to other Markdown files and verify that image paths resolve from the page containing them.
 4. The [Supported boards](../supported-boards/index.md) page is generated from `boards.txt`: do not edit it. After changing `boards.txt`, run `python docs/hooks/supported_boards.py` (or any MkDocs build) and commit the updated `docs/supported-boards/index.md`; the documentation check fails if it is out of date. Optional `# Docs: field=value` comments placed directly above a board option (`<group>.menu.pnum.<option>=...`) add metadata: `release`, `mcu`, `url` and `notes`; above a `<group>.name=` line, `url` links the category. Options without `release` get their first release from Git tags, so keep full Git history and tags available when building the documentation.
-5. Create a persistent virtual environment under your home directory once, then install or update the documentation dependencies from the core repository:
+5. The [Doxygen API reference](#doxygen-api-reference) is generated from the comments in the source code: to change it, edit the comments in the sources, not the documentation pages. Documentation-only builds work without Doxygen installed.
+6. Create a persistent virtual environment under your home directory once, then install or update the documentation dependencies from the core repository:
 
 ```bash
 python3 -m venv "$HOME/.venvs/stm32duino-docs"
@@ -39,18 +40,79 @@ Open `http://127.0.0.1:8000/dev/`. This exercises links under the `/dev/` prefix
 
 The static preview tests the selected version's files and paths, not Mike's deployed version list or redirects. To inspect the actual locally deployed versions and default redirect, use `mike serve` from a checkout whose configured `gh-pages` branch already contains those deployments.
 
+## Doxygen API reference
+
+The source-level API reference (classes, structures, functions and their parameters of the core, its libraries, the STM32 system files and the variants) is generated with [Doxygen](https://www.doxygen.nl/) from the comments in the source code. It is not written by hand: improve it by editing the Doxygen comments in the sources, not the generated pages.
+
+The reference is part of the versioned site and is published at `/<version>/doxygen/`, for example `/dev/doxygen/` or `/latest/doxygen/`. It is linked from the [Arduino API](../API.md) page, from the home page, and from the **Core Reference** section of the navigation.
+
+### Files
+
+| File | Purpose |
+| --- | --- |
+| `doxygen/Doxyfile` | Doxygen configuration: scope, preprocessor definitions, output location. |
+| `doxygen/mainpage.md` | Main page of the reference. |
+| `doxygen/html-header.html` | HTML header template: link back to the documentation site and version selector. |
+| `doxygen/version-selector.js` | Version selector: lists the versions from the Mike `versions.json` file of the site. |
+| `docs/hooks/doxygen.py` | MkDocs hook that adds the generated Doxygen pages to the site under the same version prefix. |
+
+### Comment conventions
+
+- API contracts (`@brief`, `@param`, `@return`, `@note`) are written in the header files. Do not duplicate them in the source file.
+- Static and source-only functions are documented directly above their definition in the `.c`/`.cpp` file.
+- The ST HAL, LL and CMSIS drivers (`system/Drivers`), the middlewares (`system/Middlewares`) and `cores/arduino/api` (ArduinoCore-API) are excluded from the reference.
+- Only documented items are listed (`EXTRACT_ALL = NO`).
+- Code under a guard such as `HAL_TIM_MODULE_ENABLED` is only documented if the macro is listed in `PREDEFINED` in `doxygen/Doxyfile`. Add the macro there when a new guard hides documented code.
+- Source listings are not generated, to keep every published version small; the reference links to the declarations, and the sources are on GitHub.
+
+### Build locally
+
+Install Doxygen 1.9.8 or later (`sudo apt-get install doxygen` on Debian/Ubuntu), then run, from the repository root:
+
+```bash
+STM32_CORE_VERSION=$(sed -n 's/^version=//p' platform.txt) doxygen doxygen/Doxyfile
+```
+
+The HTML pages are written to `build/doxygen/`, which is ignored by Git. Open `build/doxygen/index.html` to review them. Doxygen warnings are printed on the standard error: fix those that concern the comments you changed.
+
+To check the reference inside the documentation site, run the Doxygen command above first, then build or serve the site as described in [Update documentation](#update-documentation) and [Preview locally](#preview-locally). When `build/doxygen/` exists, MkDocs adds its pages to the site at `doxygen/`. When it does not, MkDocs adds a placeholder `doxygen/index.html` page, so documentation-only builds, including `mkdocs build --strict`, work without Doxygen installed; the workflows never publish the placeholder because they build the real reference first.
+
+### Version selector
+
+Every Doxygen page shows a **← STM32duino documentation** link, which goes to the home page of the same documentation version, and a **Version** selector. The selector lists the versions published by Mike (`dev`, `latest` and each release) and opens the same page in the selected version. If that page does not exist in the selected version, for example because the version was published before the reference was added or the page was renamed, it opens the Doxygen home page of that version, and then the documentation home page of that version.
+
+The selector reads `versions.json` from the site root, so it only appears on a published site or on a preview that contains it. A preview built with `mkdocs build --site-dir /tmp/stm32duino-docs-preview/dev` has no `versions.json`: the selector is hidden, the link back still works.
+
+### Maintenance
+
+- `doxygen/html-header.html` is based on the default header of Doxygen 1.9.8 (`doxygen -w html header.html footer.html style.css`). When the Doxygen version used by the workflows changes, regenerate the default header, reapply the two additions (the `version-selector.js` script and the `doc-nav` cell with the link and the selector) and check the pages again.
+- The Doxygen version is the one installed from the `ubuntu-latest` runner image by the workflows.
+
 ## Pull request checks
 
-The `Documentation build` workflow runs `mkdocs build --strict` on every pull request, including pull requests that do not edit documentation. It also runs on `main` when documentation sources, the MkDocs configuration, its dependencies, or the workflow change. The `main` branch requires the `Documentation build / build` status check, including for administrators, so a failed or missing result blocks merging.
+The `Documentation build` workflow installs Doxygen, builds the API reference, runs `mkdocs build --strict` and fails if the reference is not part of the generated site. It runs on every pull request, including pull requests that do not edit documentation. It also runs on `main` when documentation sources, the Doxygen configuration, the MkDocs configuration, its dependencies, the workflow, or the sources documented by Doxygen (`cores/`, `libraries/`, `variants/`, `system/` except `Drivers/` and `Middlewares/`) change. The `main` branch requires the `Documentation build / build` status check, including for administrators, so a failed or missing result blocks merging.
+
+Doxygen warnings do not fail the check, but they are visible in the log of the `Build Doxygen API reference` step.
 
 If branch protection for `main` is recreated or changed, keep `Documentation build / build` as a required status check.
 
 ## Publish a release
 
-The documentation publisher uses Mike to keep versioned snapshots on the `gh-pages` branch of `stm32duino/stm32duino.github.io`:
+The documentation publisher uses Mike to keep versioned snapshots on the `gh-pages` branch of `stm32duino/stm32duino.github.io`. Before running Mike, the workflow installs Doxygen and builds the API reference, so each snapshot contains the Doxygen pages generated from the sources of the commit or tag being published:
 
-- Documentation changes merged to `main` publish the development version at `/dev/`. The first publish sets `dev` as the site default; later development publishes leave the existing default unchanged.
-- Pushing an exact semantic-version tag such as `3.0.0` publishes that release at `/3.0.0/`.
+- Documentation or documented-source changes merged to `main` publish the development version at `/dev/` (documentation at `/dev/`, API reference at `/dev/doxygen/`). The first publish sets `dev` as the site default; later development publishes leave the existing default unchanged.
+- Pushing an exact semantic-version tag such as `3.0.0` publishes that release at `/3.0.0/` (API reference at `/3.0.0/doxygen/`).
 - When the pushed tag is the highest semantic-version tag in the core repository, the workflow also moves the `latest` alias and sets it as the site default. Older release tags are published without changing `latest`.
 
-Use the normal core release process to create and push the release tag. The documentation workflow runs from that tag automatically; no manual Mike command is needed. GitHub release tags must use the exact `MAJOR.MINOR.PATCH` form for this workflow.
+Use the normal core release process to create and push the release tag. The documentation workflow runs from that tag automatically; no manual Mike command is needed. GitHub release tags must use the exact `MAJOR.MINOR.PATCH` form, with a major version below 1000, for this workflow. The legacy date tags such as `2018.1.18` are not release tags: they are ignored when the highest release is computed, so they never prevent `latest` from moving, and a new tag in that form is rejected.
+
+Releases published before the Doxygen reference was added do not contain it; the version selector falls back to the documentation home page of those versions.
+
+### Supported boards after a release
+
+The **First release** column of the [Supported boards](../supported-boards/index.md) page is computed from the Git tags each time the documentation is built. A board that is in `boards.txt` but in no release tag yet shows **Next release**.
+
+- The workflow builds from the release tag, which is fetched with the full history, so the `/<X.Y.Z>/` documentation published for the tag already shows the new release number for the boards it contains. Pages of older versions are not rebuilt and keep their labels.
+- The generated `docs/supported-boards/index.md` committed on `main` is not updated by the workflow. Once the tag exists, it differs from a fresh build, so the `Documentation build` check fails on the next pull request until it is regenerated. After pushing a release tag, run `python docs/hooks/supported_boards.py` from a clone that has the tags (`git fetch --tags`) and commit `docs/supported-boards/index.md`.
+- The `dev` documentation shows the new release numbers at its next publish.
+- To pin a different value for a board, add a `# Docs: release=<version>` comment above its option in `boards.txt`.

docs/hooks/doxygen.py

@@ -0,0 +1,50 @@
+import logging
+from pathlib import Path
+
+from mkdocs.structure.files import File
+
+log = logging.getLogger("mkdocs.hooks.doxygen")
+
+# Doxygen HTML output, see doxygen/Doxyfile (relative to the repository root).
+# Its last component is the folder of the generated site: <site>/<version>/doxygen/
+DOXYGEN_OUTPUT = Path("build/doxygen")
+
+PLACEHOLDER = """<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Doxygen API reference not generated</title></head>
+<body>
+<h1>Doxygen API reference not generated</h1>
+<p>This build does not contain the Doxygen API reference.
+Run <code>doxygen doxygen/Doxyfile</code> from the repository root, then build the site again.</p>
+</body>
+</html>
+"""
+
+
+def on_files(files, config):
+    """Add the Doxygen HTML pages to the site, under the same version prefix."""
+    output = Path(config.config_file_path).parent / DOXYGEN_OUTPUT
+    if not (output / "index.html").is_file():
+        # Keep the links to the reference valid in builds made without Doxygen.
+        log.info(
+            "Doxygen output not found in '%s': adding a placeholder page. "
+            "Run 'doxygen doxygen/Doxyfile' before building to include the API reference.",
+            DOXYGEN_OUTPUT,
+        )
+        files.append(File.generated(config, f"{DOXYGEN_OUTPUT.name}/index.html", content=PLACEHOLDER))
+        return files
+
+    count = 0
+    for path in sorted(output.rglob("*")):
+        if path.is_file():
+            files.append(
+                File(
+                    path.relative_to(output.parent).as_posix(),
+                    str(output.parent),
+                    config.site_dir,
+                    config.use_directory_urls,
+                )
+            )
+            count += 1
+    log.info("Added %d Doxygen API reference files from '%s'", count, DOXYGEN_OUTPUT)
+    return files

docs/hooks/supported_boards.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 
 
-RELEASE_TAG_PATTERN = re.compile(r"^\d+\.\d+\.\d+$")
+RELEASE_TAG_PATTERN = re.compile(r"^\d{1,3}\.\d+\.\d+$")
 DOCS_PATTERN = re.compile(r"^# Docs: (mcu|url|notes|release)=(.*)$")
 PART_PATTERN = re.compile(
     r"MP1\d\d[A-F]|WBA\d\d[A-Z][0-9A-Z]|WLE\d[A-Z][0-9A-Z]|W[BL][0-9A-Z]{2}[A-Z][0-9A-Z]"