GitHub Pages Setup Guide

This guide explains how to set up GitHub Pages for this project to enable automatic documentation deployment.

Prerequisites

  • Your repository on GitHub

  • Admin or write access to the repository

  • GitHub Actions enabled (usually enabled by default)

Step-by-Step Setup

1. Enable GitHub Pages

For repositories you own:

  1. Go to your GitHub repository

  2. Click on Settings (top navigation bar)

  3. In the left sidebar, click Pages (under “Code and automation”)

  4. Under “Build and deployment” > “Source”

  5. Select GitHub Actions as the source

  6. Click Save

2. Configure Workflow Permissions

  1. Go to Settings > Actions > General (left sidebar)

  2. Under “Workflow permissions” section:

    • Select Read and write permissions

    • Check the box: “Allow GitHub Actions to create and approve pull requests”

  3. Click Save

3. Verify Workflow Files

Ensure these files exist in your repository (automatically created):

  • .github/workflows/deploy-docs.yml - Handles documentation deployment

  • .github/workflows/ci.yml - Handles code quality checks

You can view these files by navigating to the .github/workflows/ directory in your repository.

4. Trigger Initial Deployment

Option A: Automatic (Recommended)

Push code to the master branch:

git add .
git commit -m "Enable GitHub Pages deployment"
git push origin master

Option B: Manual Trigger

  1. Go to the Actions tab in your repository

  2. On the left, select “Deploy Documentation to GitHub Pages”

  3. Click the “Run workflow” button (right side)

  4. Select the master branch

  5. Click “Run workflow”

5. Wait for Deployment

  1. Go to the Actions tab

  2. Watch the workflow run:

    • deploy job: Builds documentation (5-10 minutes usually)

    • deploy job: Deploys to GitHub Pages (1-2 minutes)

6. Access Your Documentation

Once deployment completes:

  1. Go to Settings > Pages to see your GitHub Pages URL

  2. Your documentation will be available at: https://zlatanstajic.github.io/python_scripts/

Customizing Deployment

Changing the Repository URL

The deploy workflow references the example GitHub Pages URL. If you forked this repository, update the documentation URL:

In docs/installation.rst:

This project is configured with the GitHub username zlatanstajic and repository name python_scripts.

If you forked this repository to your own account, update the URL in documentation files:

Change: https://zlatanstajic.github.io/python_scripts/ To: https://<your-username>.github.io/<your-repo-name>/

Changing Python Version

To use a different Python version for building documentation:

In .github/workflows/deploy-docs.yml:

Find the “Set up Python” step and change:

python-version: '3.10'

To your preferred version (3.10, 3.11, 3.12, etc.).

Triggering on Different Branches

To deploy from a different branch:

In .github/workflows/deploy-docs.yml:

Change the on.push.branches section:

on:
  push:
    branches:
      - master    # Change to your branch name

Excluding Paths From Triggering

To avoid rebuilding docs on certain file changes:

In .github/workflows/deploy-docs.yml:

Modify the paths section under push or remove it entirely to trigger on all changes.

Troubleshooting

Workflow appears stuck or not running

  1. Check if GitHub Actions is enabled: * Settings > Actions > General > “Actions permissions” * Select: “Allow all actions and reusable workflows”

  2. Verify branch protection rules don’t block workflows: * Settings > Branches > Branch protection rules * Uncheck: “Require status checks to pass before merging”

Pages not showing deployed documentation

  1. Verify GitHub Pages is enabled: * Settings > Pages > Source should be “GitHub Actions”

  2. Check workflow has read-write permissions: * Settings > Actions > General > Workflow permissions * Ensure “Read and write permissions” is selected

  3. Check for build errors: * Go to Actions tab * Click on the failed workflow run * Expand the “Build” job to see error messages

Getting “Permission denied” error

  1. Go to Settings > Actions > General

  2. Under “Workflow permissions”

  3. Select “Read and write permissions”

  4. Check “Allow GitHub Actions to create and approve pull requests”

  5. Click Save

Documentation shows old version

  1. Clear browser cache (Ctrl+Shift+Del or Cmd+Shift+Del)

  2. Wait a few minutes for GitHub Pages to update

  3. Check the Actions tab to confirm latest deployment completed

Domain not pointing correctly

This typically happens with custom domains:

  1. Check that CNAME file exists in your docs directory

  2. Verify DNS settings for your custom domain

  3. Check GitHub Pages settings for proper domain configuration

More Help

For project-specific help, see the CI/CD Pipeline Documentation.