Documentation Workflow#

guides/docs/_static/documentation-workflow.png

This project utilizes a GitHub Actions workflow to streamline documentation generation and deployment. The workflow automates the following processes:

  • Building documentation using Sphinx whenever code changes are pushed, pull requests are submitted, or the workflow is manually triggered.

  • Deploying the built documentation to GitHub Pages when there’s a direct push to the dev branch.

Workflow Configuration

The workflow configuration is located within a .github/workflows/documentation.yaml file and comprises the following components:

Triggers

  • push: Triggers the workflow on code pushes to any branch.

  • pull_request: Triggers the workflow when a pull request is opened or updated.

  • workflow_dispatch: Allows for manual execution of the workflow.

Permissions

  • contents: write: Provides the workflow with the necessary permissions to push the updated documentation to GitHub Pages.

Jobs

  1. docs

    • Environment: Executes on an Ubuntu-based virtual machine.

    • Code Checkout: Retrieves a copy of the project’s repository.

    • Python Setup: Prepares a Python 3.9 environment.

    • Dependency Installation: Installs Sphinx, required themes and extensions, plus linting and testing tools. Also, installs both project-wide dependencies and documentation-specific dependencies if their corresponding requirements files exist.

    • Documentation Build: Runs sphinx-build to generate the HTML documentation.

    • GitHub Pages Deployment: Deploys the documentation (from the docs/_build directory) to the gh-pages branch, replacing any previous content.

Example Usage

  1. Update your project’s documentation within the docs directory.

  2. Push your changes to the repository or open a pull request.

  3. The workflow will automatically build the documentation.

  4. If you pushed directly to the dev branch, the built documentation will be live on https://erik-ingwersen-ey.github.io/peloptimize.

Additional Notes

  • The workflow uses standard Sphinx conventions for documentation structure.

  • Documentation specific dependencies are defined inside requirements.txt.