Skip to content

Commit 46e2542

Browse files
szaghiszaghi
committed
docs: migrate documentation pipeline from FORD to formal + VitePress
Replace the FORD-only pipeline with formal-ford2vitepress + VitePress: move the FORD config to docs/ford.md, scaffold the VitePress site (config.mts, index.md, package.json), update fobos makedoc/deldoc rules, and add cliff.toml for git-cliff changelog generation. Refactor CI: split the monolithic ci.yml into a lean test-only job (push/PR) and a new release.yml triggered on version tags, which builds docs, deploys to GitHub Pages, and publishes GitHub releases. Add a reusable composite action for build environment setup.
1 parent ce99144 commit 46e2542

File tree

14 files changed

+5284
-88
lines changed

14 files changed

+5284
-88
lines changed

‎.github/actions/setup-build-env/action.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Setup build environment
2+
description: Install GCC and Python build tools required by CI and release jobs
3+
4+
inputs:
5+
gcc-version:
6+
description: GCC version to install
7+
default: '14'
8+
extra-pip-packages:
9+
description: Space-separated list of additional pip packages
10+
default: ''
11+
12+
runs:
13+
using: composite
14+
steps:
15+
16+
- name: Install GCC
17+
shell: bash
18+
run: |
19+
sudo add-apt-repository --yes ppa:ubuntu-toolchain-r/test
20+
sudo apt update
21+
sudo apt install -y \
22+
gcc-${{ inputs.gcc-version }} \
23+
gfortran-${{ inputs.gcc-version }} \
24+
g++-${{ inputs.gcc-version }}
25+
sudo update-alternatives \
26+
--install /usr/bin/gcc gcc /usr/bin/gcc-${{ inputs.gcc-version }} 100 \
27+
--slave /usr/bin/gfortran gfortran /usr/bin/gfortran-${{ inputs.gcc-version }} \
28+
--slave /usr/bin/gcov gcov /usr/bin/gcov-${{ inputs.gcc-version }}
29+
30+
- name: Install Python tools
31+
shell: bash
32+
run: |
33+
pip install \
34+
markdown markdown-include python-markdown-math \
35+
toposort jinja2 pygments beautifulsoup4 \
36+
tqdm importlib-metadata ford FoBiS.py \
37+
${{ inputs.extra-pip-packages }}
38+
39+
- name: Check system
40+
shell: bash
41+
run: |
42+
gfortran --version
43+
gcov --version
44+
python --version
45+
FoBiS.py --version
46+
ford --version

‎.github/workflows/ci.yml‎

Lines changed: 16 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,29 @@
11
name: CI
22

3-
on: push
3+
on:
4+
push:
5+
branches: ["**"]
6+
tags-ignore: ["**"] # tags are handled by release.yml
7+
pull_request:
48

59
jobs:
6-
test-deploy:
7-
10+
test:
811
runs-on: ubuntu-latest
9-
permissions:
10-
contents: write
1112

1213
steps:
13-
- name: PREPARE SYSTEM
14-
run: |
15-
python --version
16-
gfortran --version
17-
gcov --version
18-
sudo apt install graphviz
19-
pip install --upgrade markdown
20-
pip install --upgrade markdown-include
21-
pip install --upgrade python-markdown-math
22-
pip install --upgrade toposort
23-
pip install --upgrade jinja2
24-
pip install --upgrade pygments
25-
pip install --upgrade beautifulsoup4
26-
pip install --upgrade graphviz
27-
pip install --upgrade tqdm
28-
pip install --upgrade importlib-metadata
29-
pip install --upgrade ford && ford --version
30-
pip install --upgrade FoBiS.py && FoBiS.py --version
31-
32-
- name: CHECKOUT
33-
id: checkout
34-
run: |
35-
git clone --recursive https://github.com/$GITHUB_REPOSITORY ./
36-
git log -n 1
37-
tag=`git tag | tail -n 1`
38-
echo "RELEASE=$tag" >> $GITHUB_ENV
39-
40-
- name: MAKE TAR
41-
run: |
42-
echo "release version:" ${{ env.RELEASE }}
43-
FoBiS.py rule -ex maketar
44-
ls *.tar.gz
4514

46-
- name: DEPLOY ASSET
47-
if: ${{ !env.ACT }}
48-
uses: "marvinpinto/action-automatic-releases@latest"
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
4917
with:
50-
repo_token: "${{ secrets.GITHUB_TOKEN }}"
51-
automatic_release_tag: ${{ env.RELEASE }}
52-
prerelease: false
53-
title: ${{ env.RELEASE }}
54-
files: |
55-
*.tar.gz
56-
./scripts/install.sh
57-
58-
- name: MAKE COVERAGE
59-
run: |
60-
FoBiS.py rule -ex makecoverage
18+
submodules: 'true'
6119

62-
- name: UPLOAD COVERAGE to CODECOV
63-
if: ${{ !env.ACT }}
64-
uses: codecov/codecov-action@v3
20+
- name: Setup build environment
21+
uses: ./.github/actions/setup-build-env
6522

66-
- name: MAKE DOC
67-
run: |
68-
FoBiS.py rule -ex makedoc
23+
- name: Run tests with coverage
24+
run: FoBiS.py rule -ex makecoverage
6925

70-
- name: PUSH DOC to GH Pages
71-
if: ${{ !env.ACT }}
72-
uses: JamesIves/github-pages-deploy-action@v4
26+
- name: Upload coverage to Codecov
27+
uses: codecov/codecov-action@v4
7328
with:
74-
folder: doc/html
29+
token: ${{ secrets.CODECOV_TOKEN }}

‎.github/workflows/install.yml‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,35 @@
11
name: Test (alternative) Install Methods
22

3-
on: push
3+
on:
4+
release:
5+
types: [published]
46

57
jobs:
68
install:
79

810
runs-on: ubuntu-latest
911
permissions:
10-
contents: write
12+
contents: read
13+
env:
14+
TAG: ${{ github.event.release.tag_name }}
1115

1216
steps:
13-
- name: INSTALL SCRIPT + make
14-
run: |
15-
wget $(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/releases/latest | grep 'browser_' | cut -d\" -f4 | grep -i install.sh)
16-
chmod +x install.sh
17-
./install.sh --download wget --build make
18-
rm -rf *
19-
2017
- name: INSTALL SCRIPT + cmake
2118
run: |
22-
wget $(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/releases/latest | grep 'browser_' | cut -d\" -f4 | grep -i install.sh)
19+
WORKDIR=$(mktemp -d)
20+
cd "$WORKDIR"
21+
wget $(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/releases/tags/$TAG | jq -r '.assets[] | select(.name | test("install.sh"; "i")) | .browser_download_url')
2322
chmod +x install.sh
2423
./install.sh --download wget --build cmake
25-
rm -rf *
24+
25+
- name: Setup fpm
26+
uses: fortran-lang/setup-fpm@v9
27+
with:
28+
github-token: ${{ secrets.GITHUB_TOKEN }}
2629

2730
- name: FPM
2831
run: |
32+
WORKDIR=$(mktemp -d)
33+
cd "$WORKDIR"
2934
git clone https://github.com/$GITHUB_REPOSITORY ./
30-
wget $(curl -s https://api.github.com/repos/fortran-lang/fpm/releases/latest | grep 'browser_' | cut -d\" -f4 | grep -i linux | grep -vi sha256) -O fpm
31-
chmod +x fpm
32-
./fpm build --profile release
33-
35+
fpm build --profile release

‎.github/workflows/release.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags: ["v[0-9]+.[0-9]+.[0-9]+"]
6+
7+
jobs:
8+
release:
9+
runs-on: ubuntu-latest
10+
permissions:
11+
contents: write
12+
13+
steps:
14+
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
with:
18+
submodules: 'true'
19+
20+
- name: Setup build environment
21+
uses: ./.github/actions/setup-build-env
22+
with:
23+
extra-pip-packages: formal-ford2vitepress
24+
25+
- name: Check formal version
26+
run: formal --version
27+
28+
- name: Setup Node.js
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: '20'
32+
33+
# ── Tests & coverage ────────────────────────────────────────────────────
34+
- name: Run tests with coverage
35+
run: FoBiS.py rule -ex makecoverage
36+
37+
- name: Upload coverage to Codecov
38+
uses: codecov/codecov-action@v4
39+
with:
40+
token: ${{ secrets.CODECOV_TOKEN }}
41+
42+
# ── Documentation ────────────────────────────────────────────────────────
43+
- name: Build documentation
44+
run: |
45+
formal generate --mirror-sources --diagrams --project docs/ford.md --output docs/api
46+
cd docs && npm ci && npm run docs:build
47+
48+
- name: Deploy docs to GitHub Pages
49+
uses: JamesIves/github-pages-deploy-action@v4
50+
with:
51+
branch: gh-pages
52+
folder: docs/.vitepress/dist
53+
54+
# ── Release artefact ─────────────────────────────────────────────────────
55+
- name: Build release tarball
56+
run: |
57+
VERSION="${{ github.ref_name }}"
58+
tar --xform="s%^%FLAP-${VERSION}/%" -czf "FLAP-${VERSION}.tar.gz" \
59+
--exclude='.git' \
60+
--exclude='docs/node_modules' \
61+
--exclude='docs/.vitepress/dist' \
62+
--exclude='docs/.vitepress/cache' \
63+
--exclude='exe' --exclude='obj' --exclude='mod' \
64+
*
65+
echo "TARBALL=FLAP-${VERSION}.tar.gz" >> $GITHUB_ENV
66+
67+
# ── Release notes from CHANGELOG.md ─────────────────────────────────────
68+
- name: Extract release notes from CHANGELOG.md
69+
run: |
70+
python3 - "${{ github.ref_name }}" CHANGELOG.md > release_notes.md <<'PYEOF'
71+
import sys, re
72+
tag, path = sys.argv[1], sys.argv[2]
73+
with open(path) as f:
74+
content = f.read()
75+
pattern = rf'(## \[{re.escape(tag)}\].*?)(?=\n## |\Z)'
76+
match = re.search(pattern, content, re.DOTALL)
77+
print(match.group(1).strip() if match else f"Release {tag}\n\nSee CHANGELOG.md for details.")
78+
PYEOF
79+
80+
# ── Publish GitHub release ───────────────────────────────────────────────
81+
- name: Publish GitHub release
82+
uses: softprops/action-gh-release@v2
83+
with:
84+
tag_name: ${{ github.ref_name }}
85+
name: ${{ github.ref_name }}
86+
body_path: release_notes.md
87+
files: |
88+
${{ env.TARBALL }}
89+
scripts/install.sh
90+
env:
91+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,8 @@ test.md
3838
# mac
3939
.DS_Store
4040

41+
42+
# VitePress
43+
docs/node_modules/
44+
docs/.vitepress/dist/
45+
docs/.vitepress/cache/

‎cliff.toml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
[changelog]
2+
header = "# Changelog\n"
3+
body = """
4+
{% if version %}\
5+
## [{{ version }}](https://github.com/szaghi/FLAP/tree/{{ version }}) \
6+
({{ timestamp | date(format="%Y-%m-%d") }})
7+
{% if previous.version %}\
8+
[Full Changelog](https://github.com/szaghi/FLAP/compare/{{ previous.version }}...{{ version }})
9+
{% endif %}\
10+
{% else %}\
11+
## [Unreleased]
12+
{% endif %}\
13+
{% for group, commits in commits | group_by(attribute="group") %}\
14+
### {{ group | upper_first }}
15+
{% for commit in commits %}\
16+
- {{ commit.message | upper_first }}\
17+
{% if commit.breaking %} ⚠ **BREAKING CHANGE**{% endif %} \
18+
([`{{ commit.id | truncate(length=7, end="") }}`](https://github.com/szaghi/FLAP/commit/{{ commit.id }}))
19+
{% endfor %}
20+
{% endfor %}\
21+
"""
22+
trim = true
23+
footer = ""
24+
25+
[git]
26+
conventional_commits = true
27+
28+
# Keep non-conventional commits too, grouped as "Miscellaneous"
29+
filter_unconventional = false
30+
31+
split_commits = false
32+
33+
# Turn #123 references into GitHub issue links
34+
commit_preprocessors = [
35+
{ pattern = '#([0-9]+)', replace = "[#$1](https://github.com/szaghi/FLAP/issues/$1)" },
36+
]
37+
38+
commit_parsers = [
39+
{ message = "^feat", group = "New features" },
40+
{ message = "^fix", group = "Bug fixes" },
41+
{ message = "^perf", group = "Performance" },
42+
{ message = "^refactor", group = "Refactoring" },
43+
{ message = "^docs", group = "Documentation" },
44+
{ message = "^test", group = "Testing" },
45+
{ message = "^build", group = "Build system" },
46+
{ message = "^ci", group = "CI/CD" },
47+
# skip pure release/chore commits from the changelog body
48+
{ message = "^chore\\(release\\)", skip = true },
49+
{ message = "^chore", group = "Miscellaneous" },
50+
# catch-all for non-conventional commits
51+
{ message = ".*", group = "Miscellaneous" },
52+
]
53+
54+
protect_breaking_commits = true
55+
filter_commits = false
56+
tag_pattern = "v[0-9]+\\.[0-9]+\\.[0-9]+"
57+
sort_commits = "oldest"

‎doc/README-FLAP.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/.vitepress/config.mts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import { withMermaid } from 'vitepress-plugin-mermaid'
2+
import apiSidebar from '../api/_sidebar.json'
3+
4+
export default withMermaid({
5+
title: 'FLAP Documentation',
6+
base: '/FLAP/',
7+
markdown: {
8+
math: true,
9+
languages: ['fortran-free-form', 'fortran-fixed-form'],
10+
languageAlias: {
11+
'fortran': 'fortran-free-form',
12+
'f90': 'fortran-free-form',
13+
'f95': 'fortran-free-form',
14+
'f03': 'fortran-free-form',
15+
'f08': 'fortran-free-form',
16+
'f77': 'fortran-fixed-form',
17+
},
18+
},
19+
themeConfig: {
20+
nav: [
21+
{ text: 'Home', link: '/' },
22+
{ text: 'API', link: '/api/' },
23+
],
24+
sidebar: {
25+
'/api/': [
26+
{
27+
text: 'API Reference',
28+
items: [
29+
{ text: 'Overview', link: '/api/' },
30+
],
31+
},
32+
...apiSidebar,
33+
],
34+
},
35+
search: {
36+
provider: 'local',
37+
},
38+
},
39+
mermaid: {},
40+
})

0 commit comments

Comments
 (0)