Pull request previews for Sphinx

Here's a step-by-step guide to help you install PushPreview in your Sphinx project.

Prerequisites

Before you begin, you'll need to have the following:

• A PushPreview account. If you don't have one, sign up for free.
• A Sphinx site created.

1. Add the workflow to your repository

To set up the PushPreview workflow in your Sphinx project:

1. Go to the .github/workflows directory in your Sphinx repository.

2. Create a new file named pushpreview.yml.

3. Copy the following content into pushpreview.yml:

   name: PushPreview
   
   on:
     pull_request_target:
       types:
         - labeled
   
   jobs:
     preview:
       runs-on: ubuntu-latest
       if: github.event.label.name == 'preview'
       steps:
         - uses: actions/checkout@v3
         - name: Comment
           run: |
             gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body "⚙️ Hang tight! PushPreview is currently building your preview. We'll share the URL as soon as it's ready."
           env:
             GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   
         - uses: actions/setup-node@v3
           with:
             node-version: 18
   
         - name: Set BASE_URL
           run: echo "BASE_URL=/github/${{ github.repository }}/${{ github.event.number }}/" >> $GITHUB_ENV
   
         - name: Build site
           run: |
             cd docs
             yarn install --frozen-lockfile
             yarn build
   
         - name: Generate preview
           uses: PushLabsHQ/pushpreview-action@1.0.6
           with:
             source-directory: ./docs/build
             github-token: ${{ secrets.GITHUB_TOKEN }}
             pushpreview-token: ${{ secrets.PUSHPREVIEW_TOKEN }}

4. Replace the actions/setup-node@v3 step to install Python instead:

   - uses: actions/setup-python@v2
     with:
       python-version: 3.8  # Adjust the Python version as needed for your project

5. Modify the Build site step to align with your Sphinx build process. For example:

   - name: Build site
     run: |
       cd docs
       pip install -r requirements.txt
       sphinx-build -b html source _build/html

6. Ensure the source-directory in the Generate preview step points to your Sphinx build output folder, typically ./_build/html:

   - name: Generate preview
     uses: PushLabsHQ/pushpreview-action@1.0.6
     with:
       source-directory: ./docs/_build/html
       github-token: ${{ secrets.GITHUB_TOKEN }}
       pushpreview-token: ${{ secrets.PUSHPREVIEW_TOKEN }}

2. Configure the GitHub secret

To configure the GitHub secret, follow these steps:

1. Generate a PushPreview token. For more information, see Authentication.

2. Go to the Settings tab of your GitHub repository or organization.

3. In the Settings menu, navigate to Secrets and chose Actions.

4. Click on New repository secret or New organization secret, depending on your choice in the previous step.

5. Use the following details to create a new token:

   • Name: PUSHPREVIEW_TOKEN
   • Token: The token you have generated.

6. Click Add secret.

3. Edit Sphinx configuration

To ensure your Sphinx site correctly supports preview builds, you'll need to adjust the base URL setting in the Sphinx configuration. This modification allows your site to correctly resolve URLs in the context of the preview environment.

Follow the steps below to make these changes:

1. Open the conf.py file located in the root directory of your Sphinx project.

2. Modify the base_url setting to dynamically adapt to different environments, particularly for preview deployments. Update the setting as follows:

   import os
   html_baseurl = os.getenv('BASE_URL', 'https://yourdomain.extension')

3. Save your changes and push the updated pushpreview.yml file to your repository.

4. Verify the installation

To ensure proper functioning of the PushPreview integration in your GitHub repository, follow these steps:

1. Create a new pull request in your GitHub repository.

2. Add the preview label to your new pull request. If the label doesn’t exist, create a new one.

   

3. Wait briefly for PushPreview to process the pull request and post a comment in the pull request thread.

4. Look for a comment from PushPreview containing a preview link. Click this link to view the changes.

Congratulations on setting up PushPreview! Your users can now view live previews of changes in pull requests, enhancing collaboration and review efficiency.