Skip to content

docs: fix incorrect claims, add missing tools, and release guide#193

Open
vredchenko wants to merge 1 commit intomainfrom
docs/audit-pr1-fix-incorrect-claims-and-release-guide
Open

docs: fix incorrect claims, add missing tools, and release guide#193
vredchenko wants to merge 1 commit intomainfrom
docs/audit-pr1-fix-incorrect-claims-and-release-guide

Conversation

@vredchenko
Copy link
Copy Markdown
Collaborator

Summary

PR 1 of the documentation audit (#187). Fixes factually incorrect content, fills completeness gaps, and adds a release procedure guide.

  • Fix ARIA definition in glossary — was incorrectly described as an image analysis system; now correctly describes it as a central metadata repository
  • Fix phantom tools in api-server.md — replaced nonexistent simulate_msg module and simulate-messages.sh with actual external_message_simulator.py; clarified dev-k8s.sh lives in smartem-devtools
  • Rewrite generate-docs.md — replaced stale tox -e docs reference with actual MDX sync + webui workflow
  • Fix database.md — enumerate all 6 migrations (was 3 + vague "apply remaining"); replace stale revision ID 6e6302f1ccb6 with actual migration filename
  • Add 4 undocumented tools to tools.md: check_schema_drift.py, db_table_totals.py, generate_api_docs.py, makeiso.sh
  • Add release procedure guide (docs/operations/releasing.md) covering smartem-decisions, smartem-epuplayer, and smartem-workspace — tag conventions, versioning, artifacts, manual releases, verification, uvx cache gotcha
  • Update operations index — link releasing and PyPI setup docs in toctree + Topics

Test plan

  • cd webui && npm run build passes — all docs sync and compile without errors
  • Visually check affected pages render correctly in dev server
  • Verify internal cross-links resolve (glossary, tools reference from api-server, releasing <-> pypi-publish)

Ref: #187

Fix factual errors identified in docs audit (#187):
- Correct ARIA definition (was claimed to be image analysis system)
- Replace phantom tools in api-server.md with actual simulator
- Rewrite generate-docs.md (was referencing nonexistent tox command)
- Fix database.md migration list (enumerate all 6, replace stale ID)
- Document 4 missing tools: check_schema_drift, db_table_totals,
  generate_api_docs, makeiso
- Add release procedure guide covering all 3 releasable packages
- Link releasing and PyPI setup docs in operations index
@vredchenko vredchenko added documentation Improvements or additions to project documentation smartem-devtools Developer tooling, documentation, and workspace configuration smartem-devtools:webui Developer dashboard web interface labels Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to project documentation smartem-devtools:webui Developer dashboard web interface smartem-devtools Developer tooling, documentation, and workspace configuration

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant