Deploy the documentation automatically to the branch gh-pages and Github Actions

[mariobehling]

Deploy the documentation automatically to the branch gh-pages and Github Actions.

Below are some pointers to deploy Sphinx documentation from the repository to GitHub Pages and configure it to work with a subdomain (e.g., evideo.eventyay.com), follow these steps:

---

1. Prepare Your Sphinx Documentation

1. Set Up Your Sphinx Project:

   • If not already set up, initialize a Sphinx project in your repository:

     sphinx-quickstart

   • Customize the conf.py file and your documentation content as needed.

2. Build Your Documentation Locally:

   • Run the following to generate the HTML files:

     make html

   • The generated files will typically be in the _build/html directory.

---

2. Create the gh-pages Branch

1. Create a new orphan branch for GitHub Pages:

   git checkout --orphan gh-pages

2. Clean up the branch:

   git rm -rf .

3. Add a .gitkeep file for now to initialize the branch:

   touch .gitkeep
   git add .gitkeep
   git commit -m "Initialize gh-pages branch"
   git push origin gh-pages

---

3. Configure Automated Deployment via GitHub Actions

1. Add a GitHub Actions workflow in your repository under .github/workflows/deploy.yml:

name: Deploy Sphinx Documentation to GitHub Pages

on:
  push:
    branches:
      - main  # Adjust this to your default branch

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: pip install sphinx sphinx-rtd-theme

      - name: Build documentation
        run: make html
        working-directory: docs  # Adjust to your Sphinx docs directory

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html

2. Commit and push the workflow file to your repository. This will trigger the deployment whenever changes are pushed to the main branch.

---

4. Add the Custom Subdomain

1. In the gh-pages branch, create a file named CNAME:

   echo "evideo.eventyay.com" > CNAME
   git add CNAME
   git commit -m "Add custom domain"
   git push origin gh-pages

2. Ensure the CNAME file is present in the root directory of the gh-pages branch.

---

5. Configure Your DNS

1. Go to your domain registrar's DNS management page
2. Add a CNAME record pointing evideo.eventyay.com to:

   <your-github-username>.github.io
   

---

6. Verify the Deployment

1. Navigate to Settings > Pages in your GitHub repository.
2. Ensure the source is set to the gh-pages branch.
3. Visit evideo.eventyay.com to verify the documentation is live.