Skip to content

Commit a179c6d

Browse files
fpistmfpistm
authored
Merge pull request #3102 from fpistm/doc
docs: add Doxygen API reference to the versioned documentation site
2 parents 6a2cdda + 8544d8e commit a179c6d

1,136 files changed

Lines changed: 7752 additions & 5363 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/Arduino-build.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ on:
99
- '*.json'
1010
- '**.md'
1111
- docs/**
12+
- doxygen/**
1213
- mkdocs.yml
1314
- requirements-docs.txt
1415
- keywords.txt
@@ -24,6 +25,7 @@ on:
2425
- '*.json'
2526
- '**.md'
2627
- docs/**
28+
- doxygen/**
2729
- mkdocs.yml
2830
- requirements-docs.txt
2931
- keywords.txt

‎.github/workflows/Cmake.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ on:
1010
- '*.json'
1111
- '**.md'
1212
- docs/**
13+
- doxygen/**
1314
- mkdocs.yml
1415
- requirements-docs.txt
1516
- keywords.txt
@@ -22,6 +23,7 @@ on:
2223
- '*.json'
2324
- '**.md'
2425
- docs/**
26+
- doxygen/**
2527
- mkdocs.yml
2628
- requirements-docs.txt
2729
- keywords.txt

‎.github/workflows/PIO-build.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ on:
1010
- '*.json'
1111
- '**.md'
1212
- docs/**
13+
- doxygen/**
1314
- mkdocs.yml
1415
- requirements-docs.txt
1516
- keywords.txt
@@ -26,6 +27,7 @@ on:
2627
- '*.json'
2728
- '**.md'
2829
- docs/**
30+
- doxygen/**
2931
- mkdocs.yml
3032
- requirements-docs.txt
3133
- keywords.txt

‎.github/workflows/docs-check.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ on:
1010
- boards.txt
1111
- mkdocs.yml
1212
- requirements-docs.txt
13+
- doxygen/**
14+
- cores/**
15+
- libraries/**
16+
- variants/**
17+
- system/**
18+
- "!system/Drivers/**"
19+
- "!system/Middlewares/**"
1320
- .github/workflows/docs-check.yml
1421

1522
permissions:
@@ -26,6 +33,16 @@ jobs:
2633
with:
2734
python-version: "3.x"
2835
- run: python -m pip install -r requirements-docs.txt
36+
- name: Install Doxygen
37+
run: sudo apt-get update && sudo apt-get install --yes doxygen
38+
- name: Build Doxygen API reference
39+
run: |
40+
STM32_CORE_VERSION=$(sed -n 's/^version=//p' platform.txt)
41+
export STM32_CORE_VERSION
42+
doxygen doxygen/Doxyfile
43+
test -f build/doxygen/index.html
2944
- run: mkdocs build --strict
45+
- name: Check the Doxygen API reference is part of the site
46+
run: grep -q 'name="generator" content="Doxygen' site/doxygen/index.html
3047
- name: Check generated supported boards page is committed
3148
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‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ on:
1111
- boards.txt
1212
- mkdocs.yml
1313
- requirements-docs.txt
14+
- doxygen/**
15+
- cores/**
16+
- libraries/**
17+
- variants/**
18+
- system/**
19+
- "!system/Drivers/**"
20+
- "!system/Middlewares/**"
1421
- .github/workflows/publish-docs.yml
1522
workflow_dispatch:
1623

@@ -33,6 +40,14 @@ jobs:
3340
with:
3441
python-version: "3.x"
3542
- run: python -m pip install -r requirements-docs.txt
43+
- name: Install Doxygen
44+
run: sudo apt-get update && sudo apt-get install --yes doxygen
45+
- name: Build Doxygen API reference
46+
run: |
47+
STM32_CORE_VERSION=$(sed -n 's/^version=//p' platform.txt)
48+
export STM32_CORE_VERSION
49+
doxygen doxygen/Doxyfile
50+
test -f build/doxygen/index.html
3651
- name: Configure Git author
3752
run: |
3853
git config user.name "github-actions[bot]"
@@ -68,11 +83,13 @@ jobs:
6883
env:
6984
VERSION: ${{ github.ref_name }}
7085
run: |
71-
if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
86+
# Core releases have a major version below 1000: this excludes the
87+
# legacy date tags such as 2018.1.18, which would otherwise sort last.
88+
if [[ ! "$VERSION" =~ ^[0-9]{1,3}\.[0-9]+\.[0-9]+$ ]]; then
7289
echo "Unsupported documentation release tag: $VERSION" >&2
7390
exit 1
7491
fi
75-
latest=$(git tag --list | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
92+
latest=$(git tag --list | grep -E '^[0-9]{1,3}\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
7693
if git ls-remote --exit-code --heads pages gh-pages >/dev/null; then
7794
git fetch pages gh-pages:gh-pages
7895
fi

‎CI/update/README.md‎

Lines changed: 73 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,84 @@
1-
# stm32variant
2-
3-
By default, generates:
4-
- *PeripheralPins.c*
5-
- *PinNamesVar.h*
6-
- *variant_generic.cpp*
7-
- *variant_generic.h*
8-
- *boards_entry.txt*
9-
- *generic_clock.c*
10-
11-
for all xml files description available in [STM32CubeMX](http://www.st.com/en/development-tools/stm32cubemx.html) database.
12-
By default, the database used is the one from GitHub:
13-
https://github.com/STMicroelectronics/STM32_open_pin_data
14-
The internal database from STM32CubeMX directory can also be used.
15-
The path have to be defined in `update_config.json`.
16-
17-
After file generation, review them carefully and please report any issue
1+
# Update scripts
2+
3+
Run scripts from the `Arduino_Core_STM32` repository root unless noted
4+
otherwise. Most scripts use settings in `CI/update/update_config.json`; they
5+
create default settings when needed.
6+
7+
## Generate generic variants
8+
9+
`python CI/update/stm32variant.py` generates `PeripheralPins.c`,
10+
`PinNamesVar.h`, `variant_generic.cpp`, `variant_generic.h`, `boards_entry.txt`,
11+
and `generic_clock.c` from STM32CubeMX XML pin descriptions. By default, it
12+
fetches the `STM32_open_pin_data` database from GitHub and processes all
13+
available descriptions. Use `--list` to list descriptions or
14+
`--series <pattern>` to generate a selected series. Use `--cube` to use the
15+
STM32CubeMX database instead; set `CUBEMX_DIRECTORY` in
16+
`CI/update/update_config.json` for that database. The configuration also uses
17+
`STM32CUBECLT_PATH` for STM32 target information.
18+
19+
`python CI/update/stm32variantv2.py` generates the same files from JSON pinout
20+
descriptions in the newer STM32Cube device-pack repositories. Use `--list` to
21+
list available pinout files or `--series <series>` to limit generation to one
22+
supported series. The repositories are managed by `stm32cubev2.py`; their
23+
location is configured with `REPOV2_LOCAL_PATH`.
24+
25+
After generation, review the files carefully and report any issue
1826
[here](https://github.com/stm32duino/Arduino_Core_STM32/issues).
1927

28+
## Update STM32Cube content
29+
30+
`python CI/update/stm32cube.py` manages the HAL drivers and CMSIS device files
31+
from the STM32Cube repositories. By default, it updates all supported series.
32+
Use `--check` to report version differences without updating, `--series
33+
<series>` to select a series, or `--path <directory>` to use a local STM32Cube
34+
repository instead of fetching from GitHub. By default, updates are prepared
35+
in a working copy; use `--local` to update the current core repository.
36+
37+
`python CI/update/stm32cubev2.py` performs the corresponding update for the
38+
newer STM32Cube repository layout, including HAL, LL, and CMSIS files. It
39+
supports the same `--check`, `--series`, `--path`, and `--local` options.
40+
41+
## Generate support files
42+
43+
`python CI/update/stm32wrapper.py` regenerates the HAL, LL, CMSIS, and related
44+
wrapper files using content already present in the core. Optional
45+
`--core <directory>` and `--cmsis <directory>` arguments select alternate core
46+
and CMSIS directories.
47+
48+
`python CI/update/stm32svd.py` updates the SVD files in the configured
49+
STM32duino SVD repository. Set `STM32CUBECLT_PATH` to an STM32CubeCLT
50+
installation and `STM32_SVD_PATH` to the SVD repository in
51+
`CI/update/update_config.json`. The script replaces the repository's `svd`
52+
directory with files selected from that CubeCLT installation.
53+
54+
`python CI/update/fqbn.py` prints the STM32 board FQBNs available in an
55+
installed Arduino core, including each board's `pnum` choices. Use `--board
56+
<pattern>` to filter the output with a regular expression and `--path
57+
<directory>` to specify the directory containing `arduino-cli`.
58+
59+
## Update ArduinoCore-API
60+
61+
`python CI/update/stm32api.py` synchronizes the ArduinoCore-API submodule with
62+
the latest upstream tag, applies eligible STM32duino pull requests and local
63+
patches, and reshapes the tree for STM32 use. It requires the submodule to be
64+
initialized, a clean submodule worktree, and the GitHub CLI (`gh`) to retrieve
65+
pull-request data.
66+
2067
## Update the STM32duino library list
2168

22-
Run `python CI/update/stm32libraries.py` from the `Arduino_Core_STM32` repository
23-
to fetch public STM32duino repositories that contain a root-level
69+
Run `python CI/update/stm32libraries.py` from the `Arduino_Core_STM32`
70+
repository to fetch public STM32duino repositories that contain a root-level
2471
`library.properties` and refresh the generated section in
2572
`docs/libraries/index.md`. The script groups libraries by their declared
2673
category, puts expansion-board libraries in a separate section, includes
2774
declared dependencies (linking STM32duino dependencies when available), and
2875
sorts entries alphabetically. Review and commit the updated documentation
2976
manually; this script is not run by CI.
3077

31-
`REPO_STM32DUINO` in `update_config.json` selects the local directory where
32-
library repositories are cloned or fetched. Absolute paths are used as
33-
configured; relative paths are resolved from the `Arduino_Core_STM32` repository
34-
root. If the file or setting is missing, the script writes the default
35-
`REPO_STM32DUINO` path (the parent of the core repository root), asks you to check the
36-
configuration, and exits; run it again after reviewing the generated setting.
78+
`REPO_STM32DUINO` in `CI/update/update_config.json` selects the local directory
79+
where library repositories are cloned or fetched. Absolute paths are used as
80+
configured; relative paths are resolved from the `Arduino_Core_STM32`
81+
repository root. If the file or setting is missing, the script writes the
82+
default `REPO_STM32DUINO` path (the parent of the core repository root), asks
83+
you to check the configuration, and exits; run it again after reviewing the
84+
generated setting.

0 commit comments

Comments
 (0)