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:
``automated-setup.yml``: This workflow automatically creates the
setup.py
file for your Python project.``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:
Checkout Repository:
The workflow checks out the code from the repository using
actions/checkout@v4
.
Prepare and Update Documentation:
This step checks if
setup.py
exists. If not, it createssetup.py
with predefined settings such as package name, author, email, etc. These settings are populated using variables like${{ vars.DOCS_MODULE }}
.
Auto-commit Changes:
All changes, including the newly created or updated
setup.py
, are committed back to the repository usingstefanzweifel/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
Checkout Repository:
Uses
actions/checkout@v4
to check out the code from the repository.
Prepare and Update Documentation:
Pulls necessary Docker images for documentation (
dunderlab/docs
andsphinxdoc/sphinx-latexpdf
).Installs required Python packages (
nbsphinx
anddunderlab-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.
Auto-commit Changes:
Commits all changes, including updated or newly created documentation files, back to the repository using
stefanzweifel/git-auto-commit-action@v5
.