feat: publish docs from repo #58
Conversation
🎯 Coverage Target Met!📈 Coverage Metrics
📊 Test Statistics
🔍 Files Needing Coverage
📝 Report generated on Node.js 22 • View workflow • Coverage by Vitest + v8 |
| branches: | ||
| - main | ||
| - next | ||
| - 'tom/docs-as-code' |
There was a problem hiding this comment.
i guess we can get rid of this now
| - name: Install Node.js | ||
| uses: actions/setup-node@v2 | ||
| with: | ||
| node-version: '18' |
| - name: Install cspell | ||
| run: npm install -g cspell | ||
|
|
||
| - name: Run cspell | ||
| run: cspell --config ./.cspell.json "./docs/**/*.md" |
There was a problem hiding this comment.
could we combine this to run via npx?
| - name: Install cspell | |
| run: npm install -g cspell | |
| - name: Run cspell | |
| run: cspell --config ./.cspell.json "./docs/**/*.md" | |
| - name: Run cspell | |
| run: npx cspell --config ./.cspell.json "./docs/**/*.md" | |
| - name: Install Node.js | ||
| uses: actions/setup-node@v2 | ||
| with: | ||
| node-version: '14' |
There was a problem hiding this comment.
can we run this on node 20?
| # Further actions... | ||
| log_message $INFO "Validating manifest in product: $product_name" | ||
| log_message $DEBUG "Validating manifest: $manifest" | ||
| ajv validate -s ./docs/schemas/manifest.schema.json -d "$manifest" --spec=draft2020 |
There was a problem hiding this comment.
could we use npx here to avoid the install:
| ajv validate -s ./docs/schemas/manifest.schema.json -d "$manifest" --spec=draft2020 | |
| npx ajv validate -s ./docs/schemas/manifest.schema.json -d "$manifest" --spec=draft2020 | |
There was a problem hiding this comment.
i assume we mean to use a draft2020 spec?
| # - SWAGGERHUB_PORTAL_SUBDOMAIN: SwaggerHub Portal subdomain | ||
|
|
||
| # Source the utility script to use its functions | ||
| source ./docs/scripts/utilities.sh |
There was a problem hiding this comment.
you should be able to use:
| source ./docs/scripts/utilities.sh | |
| source "$(dirname "${BASH_SOURCE[0]}")/utilities.sh" |
There was a problem hiding this comment.
Pull Request Overview
This PR establishes a docs-as-code workflow to keep developer.smartbear.com documentation in sync with the repository. The changes enable automatic publishing of markdown documentation from the docs/ directory to the live portal when changes are pushed to main or next branches.
- Adds comprehensive documentation for the SmartBear MCP Server product
- Creates publishing infrastructure with scripts to deploy content to SwaggerHub Portal
- Implements GitHub Actions workflow for automated spell checking, validation, and publishing
Reviewed Changes
Copilot reviewed 15 out of 21 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/scripts/utilities.sh | Utility functions for logging across different levels |
| docs/scripts/publish-portal-content.sh | Main publishing script for deploying content to SwaggerHub Portal |
| docs/schemas/manifest.schema.json | JSON schema for validating product manifest files |
| docs/products/SmartBear MCP Server/*.md | Complete documentation for SmartBear MCP Server including setup, capabilities, and troubleshooting |
| docs/products/SmartBear MCP Server/manifest.json | Product metadata and content structure definition |
| docs/custom-words.txt | Custom dictionary for spell checking |
| .github/workflows/docs-as-code.yaml | CI/CD workflow for validation and publishing |
| .cspell.json | Spell checker configuration |
Comments suppressed due to low confidence (6)
.github/workflows/docs-as-code.yaml:31
- The checkout action version @v2 is outdated and deprecated. Consider updating to @v4 for better performance and security.
uses: actions/checkout@v2
.github/workflows/docs-as-code.yaml:34
- The setup-node action version @v2 is outdated and deprecated. Consider updating to @v4 for better performance and security.
uses: actions/setup-node@v2
.github/workflows/docs-as-code.yaml:51
- The checkout action version @v2 is outdated and deprecated. Consider updating to @v4 for better performance and security.
uses: actions/checkout@v2
.github/workflows/docs-as-code.yaml:54
- The setup-node action version @v2 is outdated and deprecated. Consider updating to @v4 for better performance and security.
uses: actions/setup-node@v2
.github/workflows/docs-as-code.yaml:85
- The checkout action version @v2 is outdated and deprecated. Consider updating to @v4 for better performance and security.
uses: actions/checkout@v2
.github/workflows/docs-as-code.yaml:56
- Node.js version 14 has reached end-of-life and is no longer supported. Consider updating to a supported version like 18 or 20.
node-version: '14'
| return | ||
| fi | ||
|
|
||
| local content_type=$(file --mime-type -b "$full_path") |
There was a problem hiding this comment.
The content_type is determined twice on consecutive lines (103 and 104). The second assignment on line 104 overwrites the first one, making line 103 redundant.
Copilot uses AI. Check for mistakes.
| - Returns: Comprehensive error details including stack traces, occurrence patterns, affected users, and error metadata. | ||
| - Use case: Deep analysis of specific errors for debugging and resolution. | ||
|
|
||
| ### `get_insight_hub_error_latest_event` |
There was a problem hiding this comment.
The function name get_insight_hub_error_latest_event is duplicated. Lines 23-29 and 30-36 both document the same function with identical descriptions and parameters.
Copilot uses AI. Check for mistakes.
| branches: | ||
| - main | ||
| - next | ||
| - 'tom/docs-as-code' |
There was a problem hiding this comment.
The temporary branch 'tom/docs-as-code' should be removed from the trigger list once testing is complete to avoid unintended deployments.
Copilot uses AI. Check for mistakes.
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v2 |
There was a problem hiding this comment.
we should update all these action versions to the latest and use pinned sha commit
Goal
To keep the docs in developer.smartbear.com in sync with our readme and easy to update with changes to the tools, the content is now in markdown in this repo and pushes to
mainwill publish the live docs (with changes tonextgoing to the internal staging area).Design
Scripts supplied by @frankkilcommins as a general-purpose docs publishing script with some amendments to place the content within
docs/rather than at the top-level of the repo.The GitHub Action fires for changes to the docs directory on next and main (and temporarily
tom/docs-as-codefor the purposes of testing this PR).