# Copyright 2025 The HuggingFace Inc. team. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This workflow handles building documentation for both main branches and PRs.
name: Documentation

on:
  # Allows running this workflow manually from the Actions tab
  workflow_dispatch:
    inputs:
      version:
        description: 'Version tag (e.g. v0.1.2) - Leave empty for standard main build'
        required: false
        type: string

  # Triggers on pushes to main that touch the docs or the sources the API reference is generated from.
  # `src/**` is included because the API reference is built from docstrings via `[[autodoc]]`: without it,
  # published API pages would go stale as soon as a docstring changed.
  push:
    branches:
      - main
    paths:
      - "docs/**"
      - "src/**"

  # Same for pull requests, so a docstring change gets a preview build and a broken `[[autodoc]]` path
  # fails the PR rather than main.
  pull_request:
    branches:
      - main
    paths:
      - "docs/**"
      - "src/**"

  release:
    types: [published]

# Ensures that only the latest commit for a PR or branch is built, canceling older runs.
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

jobs:
  # This job builds and deploys the official documentation.
  build_main_docs:
    name: Build Main Docs
    if: >
      (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'release') &&
      github.repository == 'huggingface/lerobot'
    permissions:
      contents: read
    uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@6108e850ae1cf2f71bb0815a600bcd50c39abfa7  # main
    with:
      commit_sha: ${{ github.sha }}
      package: lerobot
      # doc-builder ships a mock-deps registry entry for lerobot, so the reusable workflow takes its
      # "light install" path: `pip install ./lerobot --no-deps` plus a handful of real dependencies.
      # That is not enough to import lerobot — draccus runs `register_subclass` at import time and
      # `processor/converters.py` calls `functools.singledispatch.register(torch.Tensor)`, neither of
      # which works against a mock. Install the package for real before the build.
      pre_command: uv pip install "./lerobot[dataset]"
      # `--version main` is load-bearing: without `--not_python_module`, doc-builder falls back to
      # `lerobot.__version__` and only maps that to the default branch when it contains "dev". Our main
      # branch carries a release version (0.6.2), so omitting this would publish the main docs to
      # /lerobot/v0.6.2/ instead of /lerobot/main/ and disable notebook building.
      additional_args: >-
        ${{
          (github.event_name == 'release' && format('--version {0}', github.event.release.tag_name)) ||
          (inputs.version != '' && format('--version {0}', inputs.version)) ||
          '--version main'
        }}
    secrets:
      token: ${{ secrets.HUGGINGFACE_PUSH }}
      hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }}

  # This job builds a preview of the documentation for a pull request.
  # The result of this job triggers the 'Upload PR Documentation' workflow.
  build_pr_docs:
    name: Build PR Docs
    if: github.event_name == 'pull_request' && github.repository == 'huggingface/lerobot'
    permissions:
      contents: read
      pull-requests: write
    uses: huggingface/doc-builder/.github/workflows/build_pr_documentation.yml@6108e850ae1cf2f71bb0815a600bcd50c39abfa7  # main
    with:
      commit_sha: ${{ github.event.pull_request.head.sha }}
      pr_number: ${{ github.event.number }}
      package: lerobot
      # See the comment on build_main_docs. The PR workflow passes its own `--version pr_<n>`, so no
      # additional_args are needed here.
      pre_command: uv pip install "./lerobot[dataset]"