Docs

Do we still need system Python with new Nuitka? #2481

Workflow file for this run

	---
	name: Docs
	"on":
	workflow_call:
	inputs:
	dependency-graph-output:
	description: 'Location in the repository of the dependency graph image.'
	default: './docs/assets/dependencies.mmd'
	required: false
	type: string
	push:
	branches:
	- main

	# Defaults sets in workflow_call.inputs or workflow_dispatch.inputs are not propagated to other events.
	# We have to manually manage them: https://github.com/orgs/community/discussions/39357#discussioncomment-7500641
	env:
	dependency-graph-output: >
	${{ inputs.dependency-graph-output == null && './docs/assets/dependencies.mmd' \|\| inputs.dependency-graph-output }}

	concurrency:
	# Group workflow jobs so new commits cancels in-progress execution triggered by previous commits.
	# Source: https://mail.python.org/archives/list/[email protected]/thread/PCBCQMJF64JGRBOX7E2EE4YLKHT4DI55/
	group: ${{ github.workflow }}-${{ github.event.pull_request.number \|\| github.sha }}
	cancel-in-progress: true

	jobs:

	autofix-typo:
	name: Fix typos
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	- uses: crate-ci/[email protected]
	with:
	write_changes: true
	- name: Remove local typos binary
	run: rm ./typos
	- uses: peter-evans/[email protected]
	with:
	# We need custom PAT with workflows permissions to fix typos in .github/workflows/*.yaml` files.
	token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT \|\| secrets.GITHUB_TOKEN }}
	assignees: ${{ github.actor }}
	commit-message: "[autofix] Typo"
	title: "[autofix] Typo"
	body: >
	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	labels: "📚 documentation"
	branch: autofix-typo

	optimize-images:
	name: Optimize images
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	# XXX Waiting for a recent release for image-actions so we'll get rid of some warning annotations like
	# "Unexpected input(s) 'compressOnly'". See: https://github.com/calibreapp/image-actions/issues/128
	- uses: calibreapp/[email protected]
	id: image_actions
	with:
	githubToken: ${{ secrets.GITHUB_TOKEN }}
	compressOnly: true
	- uses: peter-evans/[email protected]
	with:
	assignees: ${{ github.actor }}
	commit-message: "[autofix] Optimize images"
	title: "[autofix] Optimize images"
	body: >
	${{ steps.image_actions.outputs.markdown }}


	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	labels: "📚 documentation"
	branch: optimize-images

	update-mailmap:
	name: Update .mailmap
	if: ${{ ! startsWith(github.event.repository.name, 'awesome-') }}
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	with:
	# Fetch all history to extract all contributors.
	fetch-depth: 0
	- name: Install uv
	run: \|
	python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
	- name: Install gha-utils
	run: >
	uv tool install --with-requirements
	https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt gha-utils
	- name: Generate .mailmap
	run: \|
	gha-utils --verbosity DEBUG mailmap-sync --skip-if-missing ./.mailmap
	- uses: peter-evans/[email protected]
	with:
	assignees: ${{ github.actor }}
	commit-message: "[autofix] Update .mailmap"
	title: "[autofix] Update `.mailmap`"
	body: >
	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	labels: "📚 documentation"
	branch: update-mailmap

	project-metadata:
	name: Project metadata
	runs-on: ubuntu-24.04
	outputs:
	is_python_project: ${{ steps.project-metadata.outputs.is_python_project }}
	package_name: ${{ steps.project-metadata.outputs.package_name }}
	is_sphinx: ${{ steps.project-metadata.outputs.is_sphinx }}
	active_autodoc: ${{ steps.project-metadata.outputs.active_autodoc }}
	steps:
	- uses: actions/[email protected]
	with:
	# Checkout pull request HEAD commit to ignore actions/checkout's merge commit. Fallback to push SHA.
	ref: ${{ github.event.pull_request.head.sha \|\| github.sha }}
	# We're going to browse all new commits.
	fetch-depth: 0
	- name: Install uv
	run: \|
	python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
	- name: Run gha-utils metadata
	id: project-metadata
	env:
	GITHUB_CONTEXT: ${{ toJSON(github) }}
	run: >
	uvx
	--with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt
	--
	gha-utils --verbosity DEBUG metadata --overwrite "$GITHUB_OUTPUT"

	update-deps-graph:
	name: Update dependency graph
	needs:
	- project-metadata
	if: fromJSON(needs.project-metadata.outputs.is_python_project)
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	- name: Install uv
	run: \|
	python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
	- name: Install pipdeptree
	run: \|
	uv --no-progress venv --python 3.13
	uv --no-progress pip install \
	--requirement https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/pipdeptree.txt
	- name: Install project
	run: \|
	uv --no-progress pip install .
	- name: Run uv for debug
	# TODO: switch from pipdeptree to uv.
	# See: https://github.com/astral-sh/uv/issues/4439#issuecomment-2183911185
	run: \|
	uv --no-progress pip tree
	- name: Run pipdeptree for debug
	run: >
	uv --no-progress run --frozen -- pipdeptree ${{ needs.project-metadata.outputs.package_name
	&& format('--packages {0}', needs.project-metadata.outputs.package_name)}}
	- name: Create dir structure
	run: \|
	mkdir -p "$(dirname "${{ env.dependency-graph-output }}")"
	# TODO: generate a graph for each extra requirement sets (like main, dev, docs, tests, ...).
	# See: https://github.com/tox-dev/pipdeptree/issues/107
	- name: Generate graph
	run: >
	uv --no-progress run --frozen -- pipdeptree ${{ needs.project-metadata.outputs.package_name
	&& format('--packages {0}', needs.project-metadata.outputs.package_name)}}
	--mermaid > ${{ env.dependency-graph-output }}
	- uses: peter-evans/[email protected]
	with:
	assignees: ${{ github.actor }}
	commit-message: "[autofix] Regenerate dependency graph"
	title: "[autofix] Regenerate dependency graph"
	body: >
	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	labels: "📚 documentation"
	branch: update-deps-graph

	update-autodoc:
	name: Update autodoc
	needs:
	- project-metadata
	if: >
	fromJSON(needs.project-metadata.outputs.is_python_project)
	&& fromJSON(needs.project-metadata.outputs.active_autodoc)
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	- name: Install uv
	run: \|
	python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
	- name: Install project dependencies
	run: \|
	uv --no-progress venv --python 3.13
	uv --no-progress sync --frozen --extra docs
	- name: Run Sphinx
	run: \|
	uv --no-progress run --frozen -- sphinx-apidoc --no-toc --module-first --force -o ./docs .
	- uses: peter-evans/[email protected]
	with:
	assignees: ${{ github.actor }}
	commit-message: "[autofix] Update Sphinx autodoc"
	title: "[autofix] Update Sphinx autodoc"
	body: >
	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	labels: "📚 documentation"
	branch: update-autodoc

	deploy-docs:
	name: Deploy Sphinx doc
	needs:
	- project-metadata
	if: fromJSON(needs.project-metadata.outputs.is_python_project) && fromJSON(needs.project-metadata.outputs.is_sphinx)
	runs-on: ubuntu-24.04
	steps:
	- uses: actions/[email protected]
	- name: Install uv
	run: \|
	python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/uv.txt
	- name: Install project dependencies
	run: \|
	uv --no-progress venv --python 3.13
	uv --no-progress sync --frozen --all-extras
	- name: Install Graphviz
	# So we can use the sphinx.ext.graphviz plugin.
	# See: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
	run: \|
	sudo apt update
	sudo apt install --yes graphviz
	- name: Build documentation
	run: \|
	uv --no-progress run --frozen -- sphinx-build -b html ./docs ./docs/html
	- name: Deploy
	uses: peaceiris/[email protected]
	with:
	github_token: ${{ secrets.GITHUB_TOKEN }}
	publish_dir: ./docs/html
	force_orphan: true

	awesome-template-sync:
	name: Sync awesome template
	if: >
	startsWith(github.event.repository.name, 'awesome-')
	&& github.event.repository.name != 'awesome-template'
	runs-on: ubuntu-24.04
	# We need custom PAT through the whole job so we get workflow permissions to update all the boilerplate .github
	# files from awesome-template.
	steps:
	- name: Initial checkout
	uses: actions/[email protected]
	with:
	token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT \|\| secrets.GITHUB_TOKEN }}
	fetch-depth: 0
	- name: Sync from template repo
	id: template_sync
	uses: AndreasAugustin/[email protected]
	with:
	github_token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT \|\| secrets.GITHUB_TOKEN }}
	source_repo_path: kdeldycke/awesome-template
	# Action will update PR only if there is file changes. is_force_push_pr also force the PR to be updated
	# only if metadata changes.
	is_force_push_pr: true
	is_allow_hooks: true
	is_pr_cleanup: true
	# Replace "/kdeldycke/awesome-template/" in URLs by "/kdeldycke/awesome-<repo_id>/".
	hooks: >
	precommit:
	commands:
	- find ./.github/ -type f -iregex ".*\.$md\\|yaml$$" -print -exec sed -i
	"s/\/kdeldycke\/awesome-template\//\/kdeldycke\/${{ github.event.repository.name }}\//g" "{}" \;
	pr_title: "[sync] Updates from `awesome-template`"
	pr_commit_msg: "[sync] Updates from awesome-template"
	pr_branch_name_prefix: "sync-awesome-template"
	pr_body: >
	Files synced from [`${SOURCE_REPO_PATH}@${TEMPLATE_GIT_HASH}`
	repository](${SOURCE_REPO}/tree/${TEMPLATE_GIT_HASH}).


	<details><summary><code>Workflow metadata</code></summary>


	> [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
	github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
	}}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


	</details>
	pr_labels: "📚 documentation"

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Do we still need system Python with new Nuitka? #2481

Workflow file

Do we still need system Python with new Nuitka? #2481

Jobs

Run details

Workflow file for this run