|
| 1 | +# Docs Analysis Action |
| 2 | + |
| 3 | +A composite GitHub Action to analyze documentation changes in pull requests and provide useful metrics and insights. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Detects documentation files changed in a PR |
| 8 | +- Calculates metrics (files changed, words added/removed) |
| 9 | +- Tracks image changes (added, modified, deleted) |
| 10 | +- Analyzes document structure (headings, title) |
| 11 | +- Identifies the most changed files |
| 12 | +- Provides outputs for use in workflows |
| 13 | + |
| 14 | +## Usage |
| 15 | + |
| 16 | +This action analyzes documentation changes to help provide better context and metrics for documentation PRs. |
| 17 | +It only runs on PRs that modify files in the docs directory or markdown files elsewhere in the repo. |
| 18 | + |
| 19 | +### Basic Example |
| 20 | + |
| 21 | +```yaml |
| 22 | +- name: Analyze Documentation Changes |
| 23 | + uses: ./.github/actions/docs-analysis |
| 24 | + id: docs-analysis |
| 25 | + with: |
| 26 | + docs-path: 'docs/' |
| 27 | + pr-ref: ${{ github.event.pull_request.head.ref }} |
| 28 | + base-ref: 'main' |
| 29 | +``` |
| 30 | +
|
| 31 | +### Complete Example with Conditionals |
| 32 | +
|
| 33 | +```yaml |
| 34 | +jobs: |
| 35 | + check-docs-changes: |
| 36 | + runs-on: ubuntu-latest |
| 37 | + steps: |
| 38 | + - name: Checkout code |
| 39 | + uses: actions/checkout@v3 |
| 40 | + with: |
| 41 | + fetch-depth: 0 |
| 42 | + |
| 43 | + - name: Analyze Documentation Changes |
| 44 | + uses: ./.github/actions/docs-analysis |
| 45 | + id: docs-analysis |
| 46 | + with: |
| 47 | + docs-path: 'docs/' |
| 48 | + pr-ref: ${{ github.event.pull_request.head.ref }} |
| 49 | + base-ref: 'main' |
| 50 | + significant-words-threshold: '100' |
| 51 | + skip-if-no-docs: 'true' |
| 52 | + |
| 53 | + - name: Create Preview Comment |
| 54 | + if: steps.docs-analysis.outputs.docs-changed == 'true' |
| 55 | + run: | |
| 56 | + echo "Found ${{ steps.docs-analysis.outputs.docs-files-count }} changed docs files" |
| 57 | + echo "Words: +${{ steps.docs-analysis.outputs.words-added }}/-${{ steps.docs-analysis.outputs.words-removed }}" |
| 58 | + |
| 59 | + if [[ "${{ steps.docs-analysis.outputs.images-total }}" != "0" ]]; then |
| 60 | + echo "Images changed: ${{ steps.docs-analysis.outputs.images-total }}" |
| 61 | + fi |
| 62 | + |
| 63 | + if [[ "${{ steps.docs-analysis.outputs.significant-change }}" == "true" ]]; then |
| 64 | + echo "This is a significant docs change!" |
| 65 | + fi |
| 66 | +``` |
| 67 | +
|
| 68 | +## Inputs |
| 69 | +
|
| 70 | +| Name | Description | Required | Default | |
| 71 | +|------|-------------|----------|---------| |
| 72 | +| `docs-path` | Path to the documentation directory | No | `docs/` | |
| 73 | +| `pr-ref` | PR reference to analyze | No | `github.event.pull_request.head.ref` | |
| 74 | +| `base-ref` | Base reference to compare against | No | `main` | |
| 75 | +| `files-changed` | Comma-separated list of files changed (alternative to git diff) | No | `` | |
| 76 | +| `max-scan-files` | Maximum number of files to scan | No | `100` | |
| 77 | +| `significant-words-threshold` | Threshold for significant text changes | No | `100` | |
| 78 | +| `skip-if-no-docs` | Whether to skip if no docs files are changed | No | `true` | |
| 79 | + |
| 80 | +## Outputs |
| 81 | + |
| 82 | +| Name | Description | |
| 83 | +|------|-------------| |
| 84 | +| `docs-changed` | Whether documentation files were changed (`true`/`false`) | |
| 85 | +| `docs-files-count` | Number of documentation files changed | |
| 86 | +| `words-added` | Number of words added to documentation | |
| 87 | +| `words-removed` | Number of words removed from documentation | |
| 88 | +| `images-added` | Number of images added | |
| 89 | +| `images-modified` | Number of images modified | |
| 90 | +| `images-deleted` | Number of images deleted | |
| 91 | +| `images-total` | Total number of images changed | |
| 92 | +| `image-names` | Comma-separated list of changed image files | |
| 93 | +| `manifest-changed` | Whether manifest.json was changed (`true`/`false`) | |
| 94 | +| `format-only` | Whether changes are formatting-only (`true`/`false`) | |
| 95 | +| `significant-change` | Whether changes are significant (`true`/`false`) | |
| 96 | +| `has-non-docs-changes` | Whether PR contains non-docs changes (`true`/`false`) | |
| 97 | +| `most-changed-file` | Path to the most changed file | |
| 98 | +| `most-changed-url-path` | URL path for the most changed file | |
| 99 | +| `most-significant-image` | Path to the most significant image | |
| 100 | +| `doc-structure` | JSON structure of document heading counts | |
0 commit comments