Configuring Workflows in GitHub

Workflows in GitHub Actions automate your development process. They can be used for a variety of tasks, such as testing code, building artifacts, and deploying applications. To set up workflows, you need to create a specific directory structure in your repository.

Creating the Workflow Directory

Follow these steps to create a .github/workflows directory in your repository, which is where your workflow files will reside:

# Navigate to your repository's root directory
cd path/to/your-repository

# Create the .github directory if it does not exist
mkdir -p .github

# Within the .github directory, create the workflows directory
cd .github
mkdir workflows

# Your directory structure should now look like this:
# your-repository/
# └── .github/
#     └── workflows/

Replace path/to/your-repository with the actual path to your repository’s root directory. This structure is a standard convention in GitHub Actions and is necessary for GitHub to recognize and execute your workflows.

Adding Workflow Files

After creating the directory structure, you can add workflow files (YAML files) into the .github/workflows directory. These files define your workflows and the conditions under which they should run. For example, you might have a workflow for automated testing and another for building documentation.

# Example of a basic workflow file structure
your-repository/
└── .github/
    └── workflows/
        ├── automated-setup.yml
        └── automated-sphinx-docs.yml

You will be using two workflow files:

  1. ``automated-setup.yml``: This workflow automatically creates the setup.py file for your Python project.

  2. ``automated-sphinx-docs.yml``: This workflow sets up a Sphinx environment automatically for your documentation.

In this example, automated-setup.yml could be a workflow for setting up your project environment, and automated-sphinx-docs.yml could be for building and deploying Sphinx documentation.

Automated Setup Generation Workflow

This workflow automates the generation and updating of setup files in a GitHub repository.

Triggers: - Manual Trigger (workflow_dispatch): Allows for manual execution of the workflow. - Push Trigger (push): Activates the workflow on every push to the repository.

Jobs:

  • Format Setup Customized:

    • Environment: The job runs on the latest Ubuntu virtual machine.

    • Permissions: It has write permissions to the repository.

  • Steps:

    1. Checkout Repository:

      • The workflow checks out the code from the repository using actions/checkout@v4.

    2. Prepare and Update Documentation:

      • This step checks if setup.py exists. If not, it creates setup.py with predefined settings such as package name, author, email, etc. These settings are populated using variables like ${{ vars.DOCS_MODULE }}.

    3. Auto-commit Changes:

      • All changes, including the newly created or updated setup.py, are committed back to the repository using stefanzweifel/git-auto-commit-action@v5.

Automated Documentation and Code Formatting Workflow

This GitHub workflow is designed to automate the process of documentation and code formatting upon manual triggering or after every push to the repository.

Triggers: - Manual Trigger (workflow_dispatch): Allows for manual execution of the workflow. - Push Trigger (push): Activates the workflow on each push to the repository.

Jobs:

  • Format Sphinx Customized

    • Environment: The job runs on the latest Ubuntu virtual machine.

    • Permissions: It has write permissions to the repository.

Steps

  1. Checkout Repository:

    • Uses actions/checkout@v4 to check out the code from the repository.

  2. Prepare and Update Documentation:

    • Pulls necessary Docker images for documentation (dunderlab/docs and sphinxdoc/sphinx-latexpdf).

    • Installs required Python packages (nbsphinx and dunderlab-docs).

    • Sets up initial documentation in the ‘docs’ directory if it does not exist, using dunderlab_docs quickstart.

    • Generates API documentation and builds HTML and Latex PDF documentation. This step is contingent on the existence of the DOCS_SUBMODULE variable.

    • Adds or updates the .readthedocs.yml configuration file for Read the Docs integration, ensuring it is set up with the required build settings and formats.

  3. Auto-commit Changes:

    • Commits all changes, including updated or newly created documentation files, back to the repository using stefanzweifel/git-auto-commit-action@v5.