clock-bigint 1.0.1

name: Docs

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  CARGO_TERM_COLOR: always

jobs:
  docs:
    name: Generate Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable

      - name: Cache dependencies
        uses: Swatinem/rust-cache@v2

      - name: Install mdBook (for specification docs)
        run: |
          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.35/mdbook-v0.4.35-x86_64-unknown-linux-gnu.tar.gz | tar xzf -
          sudo mv mdbook /usr/local/bin/

      - name: Generate API documentation
        run: |
          cargo doc --no-deps --all-features --document-private-items
          echo "<meta http-equiv=\"refresh\" content=\"0; url=clock_bigint/index.html\">" > target/doc/index.html

      - name: Check API documentation
        run: |
          # Check that all public APIs have documentation
          if cargo doc --no-deps --document-private-items 2>&1 | grep -q "warning.*missing"; then
            echo "⚠️ Some public APIs are missing documentation"
            cargo doc --no-deps --document-private-items
            exit 1
          fi

      - name: Generate specification documentation
        run: |
          if [ -f "spec/book.toml" ]; then
            cd spec
            mdbook build
            cd ..
          else
            echo "No mdBook configuration found, skipping specification docs"
          fi

      - name: Upload API documentation
        uses: actions/upload-artifact@v4
        with:
          name: api-docs
          path: target/doc/
          retention-days: 30

      - name: Upload specification documentation
        if: success()
        uses: actions/upload-artifact@v4
        with:
          name: spec-docs
          path: spec/book/
          retention-days: 30

      - name: Deploy API docs to GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: target/doc
          destination_dir: api
          keep_files: false

      - name: Check if spec docs exist
        id: check-spec-docs
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: |
          if [ -d "spec/book" ]; then
            echo "spec_docs_exist=true" >> $GITHUB_OUTPUT
          else
            echo "spec_docs_exist=false" >> $GITHUB_OUTPUT
          fi

      - name: Deploy specification docs to GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name == 'push' && steps.check-spec-docs.outputs.spec_docs_exist == 'true'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: spec/book
          destination_dir: spec
          keep_files: true

  docsrs:
    name: Check docs.rs compatibility
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable

      - name: Cache dependencies
        uses: Swatinem/rust-cache@v2

      - name: Check docs.rs build
        run: |
          # docs.rs builds with --all-features by default
          cargo doc --all-features --no-deps

      - name: Verify docs.rs metadata
        run: |
          # Check that all required fields for docs.rs are present
          if ! grep -q "^documentation.*docs.rs" Cargo.toml; then
            echo "⚠️ Missing docs.rs documentation URL in Cargo.toml"
            exit 1
          fi

          if ! grep -q "^repository.*github.com" Cargo.toml; then
            echo "⚠️ Missing repository URL in Cargo.toml"
            exit 1
          fi

          echo "✅ docs.rs metadata looks good"

  linkcheck:
    name: Check documentation links
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable

      - name: Install link checker
        run: cargo install cargo-deadlinks

      - name: Cache dependencies
        uses: Swatinem/rust-cache@v2

      - name: Generate documentation
        run: cargo doc --no-deps --all-features

      - name: Check links in documentation
        run: |
          # Check internal links in generated docs
          if command -v cargo-deadlinks &> /dev/null; then
            cargo deadlinks --dir target/doc || {
              echo "⚠️ Dead links found in documentation"
              exit 1
            }
          else
            echo "cargo-deadlinks not available, skipping link check"
          fi

      - name: Check README links
        run: |
          # Basic link check for README
          if [ -f "README.md" ]; then
            # Extract URLs and check they're not obviously broken
            grep -o 'https*://[^)]*' README.md | while read -r url; do
              if ! curl -s --head --fail "$url" &>/dev/null; then
                echo "⚠️ Potentially broken link in README: $url"
              fi
            done
          fi