Switch to GitHub Actions

.github/workflows/build.yaml

@@ -0,0 +1,39 @@
+name: Build
+
+on:
+  workflow_call:
+
+jobs:
+  build-and-cache:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ github.sha }} # Cache the entire build Python environment
+          restore-keys: |
+            build-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}
+            build-${{ env.pythonLocation }}-
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Check syntax
+        run: make test-build
+
+      - name: Cache built files
+        uses: actions/cache@v4
+        with:
+          path: build/html
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ github.sha }}
+
+      - name: Build doc
+        run: make html

.github/workflows/deploy.yaml

@@ -0,0 +1,42 @@
+name: Deploy
+
+on:
+  workflow_dispatch:  # triggered by Core to rebuild the documentation when code comments change
+  push:
+    branches: [ master ]
+
+jobs:
+  validate:
+    uses: ./.github/workflows/validate.yaml
+
+  deploy:
+    runs-on: ubuntu-latest
+
+    needs: [ validate ]  # also depends on `build-and-cache` job for cached build, not repeated to avoid building twice
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Restore built files
+        uses: actions/cache@v4
+        with:
+          path: build/html
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ github.sha }}
+          fail-on-cache-miss: true  # depend entirely on the build step
+
+      - name: Deploy built directory to openfisca.org website
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          deploy_key: ${{ secrets.OPENFISCADOTORG_DEPLOY_KEY }}
+          publish_dir: build/html
+          external_repository: openfisca/openfisca.org
+          destination_dir: doc
+          publish_branch: gh-pages
+          user_email: bot@openfisca.org
+          user_name: OpenFisca Bot
+          commit_message: Publish latest changes from  # will be suffixed with "openfisca/openfisca-doc@<commit_sha>"

.github/workflows/validate.yaml

@@ -0,0 +1,47 @@
+name: Validate
+
+on:
+  pull_request:
+  workflow_call:
+
+jobs:
+  build:
+    uses: ./.github/workflows/build.yaml
+
+  check-links:
+    runs-on: ubuntu-latest
+    needs: [ build ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Restore built files
+        uses: actions/cache@v4
+        with:
+          path: build/html
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ github.sha }}
+          fail-on-cache-miss: true  # depend entirely on the build step
+
+      - name: Serve doc
+        run: make prod &
+
+      - name: Check for internal dead links
+        run: wget --retry-connrefused --waitretry=1 --spider --recursive --page-requisites http://localhost:8000
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Lint Markdown files
+        run: make lint

Makefile

@@ -17,7 +17,7 @@ install:
 test: lint test-build
 
 test-build:
-	@${MAKE} dummy SPHINXOPTS="-q -W"
+	@${MAKE} dummy SPHINXOPTS="--quiet --fail-on-warning"
 
 lint:  # requires Node and NPM to be installed
 	@npx --yes markdownlint-cli "**/*.md"

README.md

@@ -101,3 +101,9 @@ That's it! 🙌
 ## Using icons
 
 You can use icons by choosing one from [Lucide](https://lucide.dev) and adapting the code `<i icon-name="$ICON_NAME"></i>` with the relevant icon name.
+
+## Deploy
+
+The documentation is built as a static website on GitHub Actions with Sphinx. The built files are committed and pushed to the `doc` folder of the GitHub Pages-published branch of the `openfisca.org` repository.
+
+OpenFisca-Core triggers a deployment on the Doc repository whenever a new Core version is deployed, to ensure that the Python and Web API auto-generated documentations are up to date. This is done with [`workflow_dispatch`](https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event--fine-grained-access-tokens) using a personal access token of @openfisca-bot. This personal access token has a maximum lifetime of one year, and will thus need to be updated every year.