chore: build docs on PR and push to main

This builds and checks the documentation builds and for commits on main
branch it will deploy to GitHub Pages

.devcontainer/alma9/alma9-development.Containerfile

@@ -5,7 +5,8 @@ ENV PYTHON python3
 ENV PIP pip
 ENV PYTHONDONTWRITEBYTECODE 1
 
-ENV APP_DEV_DEPS "alma9/requirements.txt"
+ENV APP_DEV_DEPS ".devcontainer/alma9/requirements.txt"
+ENV APP_DOCS_DEPS "docs/requirements.txt"
 ENV APP_MAIN_DEPS \
     python3 \
     python3-pip \
@@ -30,7 +31,8 @@ RUN dnf update -y && dnf install -y $APP_MAIN_DEPS && dnf clean all
 FROM install_main_deps as install_dev_deps
 
 COPY $APP_DEV_DEPS $APP_DEV_DEPS
-RUN $PIP install -r $APP_DEV_DEPS
+COPY $APP_DOCS_DEPS $APP_DOCS_DEPS
+RUN $PIP install -r $APP_DEV_DEPS -r $APP_DOCS_DEPS
 
 FROM install_dev_deps as install_application
 
@@ -40,5 +42,5 @@ RUN groupadd --gid=$USER_GID -r $USERNAME && \
 RUN chown -R $USERNAME:$USERNAME .
 COPY --chown=$USERNAME:$USERNAME . .
 
-COPY alma9/.bashrc /home/$USERNAME
+COPY .devcontainer/alma9/.bashrc /home/$USERNAME
 USER $USERNAME:$USERNAME

.devcontainer/alma9/devcontainer.json

@@ -2,16 +2,18 @@
 // https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/docker-existing-dockerfile
 {
 	"name": "Alma Linux 9",
-	// Sets the run context to one level up to be inside of the .devcontainer folder.
-	"context": "..",
+	// Sets the run context to two levels up to be inside of the convert2rhel project root folder.
+	"context": "../..",
 	// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
 	"dockerFile": "alma9-development.Containerfile",
 	// Uncomment the next line to run commands after the container is created - for example installing curl.
 	"postCreateCommand": "pre-commit install",
 	"runArgs": [
-		"--userns", "keep-id",
+		"--userns",
+		"keep-id",
 		// Make it easier to find the container by having the project name.
-		"--name", "convert2rhel-alma9-devcontainer"
+		"--name",
+		"convert2rhel-alma9-devcontainer"
 	],
 	// Default workspace path to open in container. Sometimes when the
 	// container crashes or you need to re-attach to the container, it opens in

.devcontainer/alma9/requirements.txt

@@ -2,5 +2,4 @@ pre-commit==3.7.1
 pytest==8.2.2
 pytest-cov==5.0.0
 coverage[toml]==7.5.3
-sphinx
-sphinx_autodoc_typehints
+sphinx==7.3.7

.devcontainer/centos7/requirements.txt

@@ -4,5 +4,3 @@ pathlib2==2.3.7.post1
 mock==3.0.5
 pytest-cov==2.12.1
 coverage[toml]==5.5
-sphinx
-sphinx_autodoc_typehints

.github/workflows/main-docs-deploy.yml

@@ -0,0 +1,46 @@
+name: "Documentation deployment"
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - uses: ammaraskar/sphinx-action@dev
+        with:
+          docs-folder: "docs/"
+          pre-build-command: "pip install -r docs/requirements.txt"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: docs/build/html/
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,18 @@
+name: "Pull Request Docs Check"
+on:
+- pull_request
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ammaraskar/sphinx-action@dev
+      with:
+        docs-folder: "docs/"
+        pre-build-command: "pip install -r docs/requirements.txt"
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: DocumentationHTML
+        path: docs/build/html/

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx_autodoc_typehints==2.1.1