feature/migrate to rst → dev (#19) #11
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # TOPST SCHOOL's GitHub Pages Dev Branch Publishing Workflow | |
| # ========================================================== | |
| # | |
| # Author: Akshay Mestry <xa@mes3.dev> | |
| # Created on: Sunday, September 01 2024 | |
| # Last updated on: Sunday, September 01 2024 | |
| # Workflow name displayed in TOPST SCHOOL's "Actions" tab. | |
| name: DEV | Build and Deploy Documents | |
| # A workflow with the following "on" value will run when a "push" is made | |
| # to the "dev" branch in the workflow's repository. For example, the "push" | |
| # event has a branches filter that causes this workflow to run only when | |
| # a push to a branch that matches the branches filter occurs, in this | |
| # case, the "dev" branch. | |
| on: | |
| push: | |
| branches: | |
| - dev | |
| # We're using permissions to modify the default permissions granted to | |
| # the ``GITHUB_TOKEN``, adding or removing access as required, so that we | |
| # only allow the minimum required access. | |
| permissions: | |
| contents: write # Only write permissions to the repository contents are needed for deployment. | |
| # A map of variables that are available to the steps of all jobs in the workflow. | |
| env: | |
| OUTPUT_DIR: docs/build/ # Directory where Sphinx will output the built HTML files. | |
| SOURCE_DIR: docs/source/ # Directory containing the Sphinx source files (rST or MD). | |
| PUBLISH_BRANCH: gh-pages # Branch where the static site will be published. | |
| PY_BUILD: 3.12.1 # Python version to be used for building the documentation. | |
| # We're using concurrency to ensure that only a single job or workflow | |
| # using the same concurrency group will run at a time. | |
| concurrency: | |
| group: ${{ github.ref }} # Groups by branch, so jobs in the same branch won't overlap. | |
| cancel-in-progress: true # Cancels any currently running jobs in the same group if a new one starts. | |
| # A workflow run is made up of one or more jobs, which run in parallel by default. | |
| # The ``ubuntu-latest`` label currently uses the Ubuntu 22.04 runner image. | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest # Runs the job on the latest available Ubuntu runner. | |
| steps: | |
| # Step 1: Check out the code from the repository to the runner. | |
| - name: Checkout TOPST SCHOOL Code (Dev) | |
| uses: actions/checkout@v4 # Checks out the repository code into the runner for the workflow to use. | |
| with: | |
| fetch-depth: 1 # Fetch only the latest commit for faster checkouts. | |
| # Step 2: Set up the specified Python version and cache pip dependencies for faster builds. | |
| - name: Set Up Python ${{ env.PY_BUILD }} | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ env.PY_BUILD }} # Sets up the Python version specified in the environment variables. | |
| cache: 'pip' # Caches pip dependencies to speed up subsequent builds. | |
| # Step 3: Install the project's Python dependencies. | |
| - name: Install Python Dependencies | |
| run: | | |
| echo "Installing Coeus..." | |
| python -m pip install --upgrade pip | |
| pip install -U git+https://github.com/xames3/coeus-sphinx-theme.git#egg=coeus-sphinx-theme | |
| # Step 4: Build the Sphinx documentation into HTML format. | |
| - name: Build Sphinx Documentation | |
| # -E: Rebuild all files, not just those that have changed. | |
| # -W: Treat warnings as errors. | |
| # -a: Write all output files (default only writes new and changed files). | |
| # -q: Run in quiet mode, with minimal output. | |
| run: | | |
| echo "Building Sphinx documentation..." | |
| sphinx-build -Eaq --builder html --define language=en ${{ env.SOURCE_DIR }} ${{ env.OUTPUT_DIR }}/en && sphinx-build -Eaq --builder html --define language=es ${{ env.SOURCE_DIR }} ${{ env.OUTPUT_DIR }}/es | |
| # Step 5: Deploy the built HTML files to the specified branch (GitHub Pages). | |
| - name: DEV | Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/dev' }} | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} # Deploys to the gh-pages branch. | |
| publish_branch: ${{ env.PUBLISH_BRANCH }} # Uses the GitHub token for authentication. | |
| publish_dir: ${{ env.OUTPUT_DIR }} # Directory to publish (the output of the Sphinx build). | |
| force_orphan: false # Do not force an orphan commit, preserving commit history. | |
| enable_jekyll: false # Disables Jekyll processing on GitHub Pages, which is unnecessary for Sphinx-generated HTML. | |
| user_email: "github-actions[bot]@users.noreply.github.com" # Email to associate with the commit. | |
| user_name: "github-actions[bot]" # Name to associate with the commit. | |
| full_commit_message: ${{ github.event.head_commit.message }} # Use the commit message from the push event. | |
| # Step 6: Provide response after deployment. | |
| - name: Notify Success | |
| if: success() | |
| run: echo "✅ Documentation successfully built and deployed to GitHub Pages (Dev)." | |
| - name: Notify Failure | |
| if: failure() | |
| run: echo "❌ Failed to build or deploy the documentation from the dev branch. Please check the logs." |