fix: stabilize public CLI bridge #78

Workflow file for this run

	name: Documentation

	on:
	push:
	branches: [ main, develop ]
	paths:
	- 'neural/*/.py'
	- 'docs/**'
	- 'examples/**'
	- 'README.md'
	- 'CHANGELOG.md'
	pull_request:
	branches: [ main ]
	paths:
	- 'neural/*/.py'
	- 'docs/**'
	- 'examples/**'
	- 'README.md'
	- 'CHANGELOG.md'
	workflow_dispatch:
	inputs:
	deploy:
	description: 'Deploy to production'
	required: false
	default: 'false'
	type: boolean

	jobs:
	generate-api-docs:
	runs-on: ubuntu-latest
	name: Generate API Documentation
	outputs:
	docs-changed: ${{ steps.changes.outputs.docs }}
	steps:
	- name: Checkout
	uses: actions/checkout@v4
	with:
	fetch-depth: 0

	- name: Detect file changes
	uses: dorny/paths-filter@v2
	id: changes
	with:
	filters: \|
	docs:
	- 'neural/*/.py'
	- 'docs/**'
	- 'examples/**'
	- 'README.md'
	- 'CHANGELOG.md'

	- name: Set up uv
	if: steps.changes.outputs.docs == 'true'
	uses: astral-sh/setup-uv@v7
	with:
	python-version: "3.11"
	enable-cache: true

	- name: Sync dependencies
	if: steps.changes.outputs.docs == 'true'
	run: uv sync --extra dev --extra docs

	- name: Generate API docs with mkdocstrings
	if: steps.changes.outputs.docs == 'true'
	run: \|
	mkdir -p docs/api
	echo "API documentation generation skipped for beta release"
	# TODO: Re-enable API doc generation in stable release
	# python -c "... complex doc generation code ..."

	- name: Generate examples documentation
	if: steps.changes.outputs.docs == 'true'
	run: \|
	mkdir -p docs/examples/generated
	uv run python scripts/generate_examples_docs.py

	- name: Validate documentation links
	if: steps.changes.outputs.docs == 'true'
	run: \|
	# Check for broken internal links
	find docs -name ".mdx" -exec grep -l "\[.\](.*.mdx)" {} \; \| while read file; do
	echo "Checking links in $file"
	grep -o "\[.\](..mdx)" "$file" \| while read link; do
	target=$(echo "$link" \| sed 's/.($.$)/\1/')
	if [ ! -f "docs/$target" ] && [ ! -f "$target" ]; then
	echo "Broken link found: $target in $file"
	exit 1
	fi
	done
	done

	- name: Check documentation quality
	if: steps.changes.outputs.docs == 'true'
	run: \|
	# Check for required sections in documentation
	uv run python scripts/validate_docs.py

	- name: Upload generated docs
	if: steps.changes.outputs.docs == 'true'
	uses: actions/upload-artifact@v4
	with:
	name: generated-docs
	path: docs/
	retention-days: 7

	validate-examples:
	runs-on: ubuntu-latest
	name: Validate Examples
	if: needs.generate-api-docs.outputs.docs-changed == 'true'
	needs: generate-api-docs
	steps:
	- name: Checkout
	uses: actions/checkout@v4

	- name: Set up uv
	uses: astral-sh/setup-uv@v7
	with:
	python-version: "3.11"
	enable-cache: true

	- name: Sync dependencies
	run: uv sync --extra dev

	- name: Test examples syntax
	run: \|
	for example in examples/*.py; do
	echo "Checking syntax of $example"
	uv run python -m py_compile "$example"
	done

	- name: Validate example imports
	run: \|
	uv run python -c "
	import ast
	import sys
	from pathlib import Path

	examples_dir = Path('examples')
	for py_file in examples_dir.glob('*.py'):
	try:
	with open(py_file) as f:
	ast.parse(f.read())
	print(f'✓ {py_file.name}: Valid syntax')
	except SyntaxError as e:
	print(f'✗ {py_file.name}: Syntax error - {e}')
	sys.exit(1)
	"

	validate-docs:
	runs-on: ubuntu-latest
	name: Validate Documentation
	needs: [generate-api-docs, validate-examples]
	if: needs.generate-api-docs.outputs.docs-changed == 'true'
	steps:
	- name: Checkout
	uses: actions/checkout@v4

	- name: Download generated docs
	uses: actions/download-artifact@v4
	with:
	name: generated-docs
	path: docs/

	- name: Set up Bun
	uses: oven-sh/setup-bun@v2

	- name: Validate Mintlify CLI availability
	run: bunx @mintlify/cli@latest --version

	- name: Validate Mintlify configuration
	run: \|
	# Validate repository Mintlify config syntax (this repo uses docs/mint.json)
	if [ -f "docs/mint.json" ]; then
	jq . docs/mint.json > /dev/null
	else
	echo "::warning::docs/mint.json not found; skipping Mintlify validation"
	exit 0
	fi

	# mintlify dev expects docs.json; run preview only when that layout exists.
	if [ -f "docs.json" ] \|\| [ -f "docs/docs.json" ]; then
	timeout 30s bunx @mintlify/cli@latest dev --no-open --port 3000 \|\| \
	echo "::warning::Documentation preview failed; continuing as advisory check"
	else
	echo "::notice::Skipping mintlify dev preview because docs.json is not present"
	fi

	- name: Documentation Summary
	run: \|
	echo "## 📚 Documentation Status" >> $GITHUB_STEP_SUMMARY
	echo "- ✅ Mint.json configuration valid" >> $GITHUB_STEP_SUMMARY
	echo "- ✅ $(find docs -name '*.mdx' \| wc -l) MDX files found" >> $GITHUB_STEP_SUMMARY
	echo "- ✅ All examples validated" >> $GITHUB_STEP_SUMMARY
	echo "- 📝 Manual deployment required via Mintlify dashboard" >> $GITHUB_STEP_SUMMARY
	echo "" >> $GITHUB_STEP_SUMMARY
	echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
	echo "1. Visit [Mintlify Dashboard](https://mintlify.com/dashboard)" >> $GITHUB_STEP_SUMMARY
	echo "2. Select project: neural-sdk" >> $GITHUB_STEP_SUMMARY
	echo "3. Click 'Deploy' to publish changes" >> $GITHUB_STEP_SUMMARY

	update-changelog:
	runs-on: ubuntu-latest
	name: Update Changelog
	if: github.ref == 'refs/heads/main' && github.event_name == 'push'
	steps:
	- name: Checkout
	uses: actions/checkout@v4
	with:
	fetch-depth: 0
	token: ${{ secrets.GITHUB_TOKEN }}

	- name: Set up uv
	uses: astral-sh/setup-uv@v7
	with:
	python-version: "3.11"
	enable-cache: true

	- name: Auto-update changelog
	run: \|
	uv run --with gitpython python scripts/update_changelog.py

	- name: Commit changelog updates
	run: \|
	git config --local user.email "action@github.com"
	git config --local user.name "GitHub Action"
	git add CHANGELOG.md
	if git diff --staged --quiet; then
	echo "No changes to commit"
	else
	git commit -m "docs: auto-update changelog [skip ci]"
	git push
	fi

Navigation Menu

Uh oh!

fix: stabilize public CLI bridge #78

Workflow file

fix: stabilize public CLI bridge #78

Uh oh!

Workflow file for this run