Generate documentation workflow (meta-pytorch/torchrec)

The Generate documentation workflow from meta-pytorch/torchrec, explained and optimized by Latchkey.

CI health: B - good

Run this on Latchkey for self-healing, caching, and up to 58% lower cost.

Grade your own workflow free or run it on Latchkey →

Source: meta-pytorch/torchrec.github/workflows/docs.ymlLicense BSD-3-ClauseView source

What it does

This is the Generate documentation workflow from the meta-pytorch/torchrec repository, a real project running GitHub Actions. It is shown here with attribution under its BSD-3-Clause license.

Below, Latchkey shows a faster, safer version produced by its optimization engine.

The workflow

workflow (.yml)

# This workflow builds the torchrec docs and deploys them to gh-pages.
name: Generate documentation
on:
  push:
    branches:
      - main
  workflow_dispatch:
  pull_request:
    paths-ignore:
      - .gitignore
      - ".github/workflows/[bcprvu]*.yml"

jobs:
  build_docs_job:
    runs-on: ${{ matrix.os }}
    permissions:
      # Grant write permission here so that the doc can be pushed to gh-pages branch
      contents: write
    strategy:
      matrix:
        include:
         - os: linux.24_04.4x
           python-version: 3.14
           python-tag: "py314"
    steps:
    - name: Check ldd --version
      run: ldd --version
    - name: Checkout
      uses: actions/checkout@v4
    # Update references
    - name: Update pip
      run: |
        sudo apt-get update
        sudo apt-get -y install python3-pip
        sudo apt upgrade python3-pip
        pip --version
    - name: Setup conda
      run: |
        wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
        bash ~/miniconda.sh -b -p $HOME/miniconda
    - name: setup Path
      run: |
        echo "/home/ec2-user/miniconda/bin" >> $GITHUB_PATH
        echo "CONDA=/home/ec2-user/miniconda" >> $GITHUB_PATH
    - name: create conda env
      run: |
        conda create --name build_binary python=${{ matrix.python-version }}
        conda info
    - name: check python version no Conda
      run: |
        python --version
    - name: check python version
      run: |
        conda run -n build_binary python --version
    - name: Install gcc
      shell: bash
      run: |
        sudo apt-get install build-essential
    - name: setup Path
      run: |
        echo /usr/local/bin >> $GITHUB_PATH
    - name: Install PyTorch
      shell: bash
      run: |
        conda run -n build_binary pip install torch --index-url https://download.pytorch.org/whl/nightly/cpu
    - name: Install fbgemm
      run: |
        conda run -n build_binary pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cpu
    - name: Install torchmetrics
      run: |
        conda run -n build_binary pip install torchmetrics==1.0.3
    - name: Install TorchRec
      run: |
        conda run -n build_binary pip install -r requirements.txt
        conda run -n build_binary python setup.py bdist_wheel --python-tag=${{ matrix.python-tag }}
    - name: Test fbgemm_gpu and torchrec installation
      shell: bash
      run: |
        conda run -n build_binary \
          python -c "import fbgemm_gpu"
        conda run -n build_binary \
          python -c "import torchrec"
    - name: Build the docset
      run: |
        conda run -n build_binary python -m pip install -r docs/requirements.txt
        cd ./docs
        conda run -n build_binary make html
        cd ..
    - name: Upload Built-Docs
      uses: actions/upload-artifact@v4
      with:
        name: Built-Docs
        path: docs/build/html/
    - name: Get output time
      run: echo "The time was ${{ steps.build.outputs.time }}"
    - name: Deploy
      if: github.ref == 'refs/heads/main'
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: docs/build/html # The folder the action should deploy.

  doc-preview:
    runs-on: [linux.2xlarge]
    needs: build_docs_job
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: Built-Docs
          path: docs
      - name: Add no-index tag
        run: |
          find docs -name "*.html" -print0 | xargs -0 sed -i '/<head>/a \ \ <meta name="robots" content="noindex">';
      - name: Upload docs preview
        uses: seemethere/upload-artifact-s3@v5
        if: ${{ github.event_name == 'pull_request' }}
        with:
          retention-days: 14
          s3-bucket: doc-previews
          if-no-files-found: error
          path: docs
          s3-prefix: meta-pytorch/torchrec/${{ github.event.pull_request.number }}

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}-${{ inputs.repository }}-${{ github.event_name == 'workflow_dispatch' }}
  cancel-in-progress: true

The same workflow, on Latchkey

Removes redundant runs and caps runaway jobs. Added and changed lines are highlighted.

# This workflow builds the torchrec docs and deploys them to gh-pages.
name: Generate documentation
on:
  push:
    branches:
      - main
  workflow_dispatch:
  pull_request:
    paths-ignore:
      - .gitignore
      - ".github/workflows/[bcprvu]*.yml"
 
jobs:
  build_docs_job:
    timeout-minutes: 30
    runs-on: ${{ matrix.os }}
    permissions:
      # Grant write permission here so that the doc can be pushed to gh-pages branch
      contents: write
    strategy:
      matrix:
        include:
         - os: linux.24_04.4x
           python-version: 3.14
           python-tag: "py314"
    steps:
    - name: Check ldd --version
      run: ldd --version
    - name: Checkout
      uses: actions/checkout@v4
    # Update references
    - name: Update pip
      run: |
        sudo apt-get update
        sudo apt-get -y install python3-pip
        sudo apt upgrade python3-pip
        pip --version
    - name: Setup conda
      run: |
        wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
        bash ~/miniconda.sh -b -p $HOME/miniconda
    - name: setup Path
      run: |
        echo "/home/ec2-user/miniconda/bin" >> $GITHUB_PATH
        echo "CONDA=/home/ec2-user/miniconda" >> $GITHUB_PATH
    - name: create conda env
      run: |
        conda create --name build_binary python=${{ matrix.python-version }}
        conda info
    - name: check python version no Conda
      run: |
        python --version
    - name: check python version
      run: |
        conda run -n build_binary python --version
    - name: Install gcc
      shell: bash
      run: |
        sudo apt-get install build-essential
    - name: setup Path
      run: |
        echo /usr/local/bin >> $GITHUB_PATH
    - name: Install PyTorch
      shell: bash
      run: |
        conda run -n build_binary pip install torch --index-url https://download.pytorch.org/whl/nightly/cpu
    - name: Install fbgemm
      run: |
        conda run -n build_binary pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cpu
    - name: Install torchmetrics
      run: |
        conda run -n build_binary pip install torchmetrics==1.0.3
    - name: Install TorchRec
      run: |
        conda run -n build_binary pip install -r requirements.txt
        conda run -n build_binary python setup.py bdist_wheel --python-tag=${{ matrix.python-tag }}
    - name: Test fbgemm_gpu and torchrec installation
      shell: bash
      run: |
        conda run -n build_binary \
          python -c "import fbgemm_gpu"
        conda run -n build_binary \
          python -c "import torchrec"
    - name: Build the docset
      run: |
        conda run -n build_binary python -m pip install -r docs/requirements.txt
        cd ./docs
        conda run -n build_binary make html
        cd ..
    - name: Upload Built-Docs
      uses: actions/upload-artifact@v4
      with:
        name: Built-Docs
        path: docs/build/html/
    - name: Get output time
      run: echo "The time was ${{ steps.build.outputs.time }}"
    - name: Deploy
      if: github.ref == 'refs/heads/main'
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: docs/build/html # The folder the action should deploy.
 
  doc-preview:
    timeout-minutes: 30
    runs-on: [linux.2xlarge]
    needs: build_docs_job
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: Built-Docs
          path: docs
      - name: Add no-index tag
        run: |
          find docs -name "*.html" -print0 | xargs -0 sed -i '/<head>/a \ \ <meta name="robots" content="noindex">';
      - name: Upload docs preview
        uses: seemethere/upload-artifact-s3@v5
        if: ${{ github.event_name == 'pull_request' }}
        with:
          retention-days: 14
          s3-bucket: doc-previews
          if-no-files-found: error
          path: docs
          s3-prefix: meta-pytorch/torchrec/${{ github.event.pull_request.number }}
 
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}-${{ inputs.repository }}-${{ github.event_name == 'workflow_dispatch' }}
  cancel-in-progress: true

What changed

Add a job timeout so a hung step cannot burn hours of runner time.

2 third-party actions are referenced by a movable tag. Pin them to the commit SHA (Latchkey resolves and applies this automatically) so a repointed tag cannot change what runs.

What Latchkey heals here

This workflow has steps that commonly fail on transient issues (network, registries, flaky browsers). On Latchkey managed runners they are detected, retried, and self-healed instead of failing your build:

Dependency installs
Network fetches

This workflow runs 2 jobs per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.

Actions used in this workflow

actions/checkout actions/upload-artifact actions/download-artifact