Skip to content

docs: refresh documentation — rename files, fix API responses, add missing content - #152

Merged
allankoechke merged 1 commit into
masterfrom
docs/refresh-docs
Aug 8, 2026
Merged

docs: refresh documentation — rename files, fix API responses, add missing content#152
allankoechke merged 1 commit into
masterfrom
docs/refresh-docs

Conversation

@allankoechke

Copy link
Copy Markdown
Owner

Summary

Comprehensive documentation refresh addressing all issues tracked in idea_board#25.

  • Rename all doc files: drop numbered prefixes and update all 53 cross-references across README, QuickStart, doc files, and docker-compose
  • Fix 7 confirmed API response mismatches found by comparing docs against source code
  • Add missing documentation: WebSocket realtime endpoint, entity list query params, application settings schema, complete MB_* environment variable list, file handling details
  • Trim QuickStart.md: cut from 400 lines to ~170 by removing sections already covered in README
  • Fix typos and naming errors in scripting.md and installation.md
  • Standardize style: remove emoji from headers (consistent with README), drop redundant H1 titles

Changes

Renames (10 files)

  • 00.installation.mdinstallation.md
  • 01.cmd.mdcmd.md
  • 02.api.mdapi.md
  • 02.auth.mdauth.md
  • 03.rules.mdrules.md
  • 05.embedding.mdembedding.md
  • 06.docker.mddocker.md
  • 11.files.mdfiles.md
  • 12.healthcheck.mdhealthcheck.md
  • 13.scripting.mdscripting.md

API Response Fixes

Endpoint Was (wrong) Now (correct)
GET /api/v1/health {"status":"ok","uptime":12345} {"status":"OK"}
POST /auth//refresh flat {token, user} {status, data:{token,user}, error}
POST /auth//logout {message:"Logged out"} {status, data:{logged_out:true}, error}
GET /sys/logs pagination page/page_size/total_pages limit/after/cursor
GET /sys/logs response {logs:[...], pagination:{...}} {data:{items, items_count, limit, cursor}}

New Documentation

  • WebSocket realtime endpoint (WS /api/v1/realtime/ws) with subscribe/unsubscribe
  • Entity list query params (limit, after, sort) — were marked [PENDING], actually implemented
  • Application settings schema (appName, baseUrl, maxFileSize, sessionTimeout, etc.)
  • Complete MB_* env var table in docker.md (MB_OAUTH_ENCRYPTION_KEY, MB_REALTIME_SSE, MB_REALTIME_WS, MB_LOG_LEVEL, etc.)
  • File storage path correction (/files// not //)
  • Filename sanitization algorithm and path traversal protection notes

Test Plan

  • Verify all doc cross-links resolve to existing files
  • Verify Doxygen docs build: cmake -DMB_BUILD_DOCS=ON + --target mantisbase-docs
  • Spot-check a few API responses against the documented formats

…ssing content

- Drop numbered prefixes from all doc files (00.installation.md → installation.md, etc.)
  and update all 53 references across README.md, QuickStart.md, doc cross-links,
  and docker/docker-compose.yaml
- Fix /api/v1/health response: returns {"status": "OK"} not {"status": "ok", "uptime": ...}
- Fix auth refresh response: correct envelope is {status, data: {token, user}, error}
- Fix auth logout response: correct body is {status, data: {logged_out: true}, error}
- Fix logs endpoint: use cursor-based pagination (limit/after) not page-based,
  and correct response structure to {data: {items, items_count, limit, cursor}}
- Remove [PENDING] from entity list query params — document actual limit/after/sort support
- Add WebSocket realtime endpoint (WS /api/v1/realtime/ws) documentation
- Add application settings schema documentation (appName, baseUrl, maxFileSize, etc.)
- Remove duplicate "Entity Types and Validation" section from api.md
- Fix file storage path: <dataDir>/files/<entity>/<filename> not <dataDir>/<entity>/<filename>
- Add filename sanitization, path traversal protection, and limitation notes to files.md
- Add all MB_* environment variables to docker.md (MB_OAUTH_ENCRYPTION_KEY,
  MB_REALTIME_SSE, MB_REALTIME_WS, MB_LOG_LEVEL, MB_DATABASE_TYPE, etc.)
- Trim QuickStart.md from 400 lines to ~170 — remove sections duplicated in README
- Fix typos in scripting.md (ay→any, reqires→requires, invokation→invocation)
- Fix "mantisapp" → "mantisbase" in scripting.md
- Fix "Mantis" → "MantisBase" in installation.md
- Remove emoji from section headers for consistency with README style
- Remove redundant H1 titles from docker.md and scripting.md (rely on @page tag)
@allankoechke allankoechke self-assigned this Aug 8, 2026
@allankoechke allankoechke added the documentation Improvements or additions to documentation label Aug 8, 2026
@allankoechke allankoechke added this to the v0.4.x milestone Aug 8, 2026
@allankoechke
allankoechke merged commit 0fa0df6 into master Aug 8, 2026
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant