From 913174cdf8e8699837fcdd0a99f12b87a4950eff Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 08:21:47 -0500 Subject: [PATCH] docs(gates): widen relative-link checker to all docs, repair the rot it finds TestDocsRelativeLinks walked only docs/developer; widening it to all of docs/ immediately surfaced the same class of rot the gate was built for, outside its old reach: - docs/index.md was the old monolith's landing page: linked the deleted api-reference.md, 10 directory-style area links, and escaped the docs tree to README/AGENTS/.env/compose. Rewritten as a portal whose every link resolves, with one representative endpoint doc per API area and pointers to the new writing-ui-docs.md standard. - directory-style links in user stubs (devices/, ../operations/) - case-mismatched links (Development.md) in contributing.md - monolith-era pointer (API_REFERENCE.md, TROUBLESHOOTING.md) and escaped AGENTS.md links in contributing/development.md - docs/development/calibre-opf-implementation.md double-up escapes, a link to the removed repo-root plan file (absorbed here), and a source-code hyperlink the docs site can't serve (now inline code) - operations/operations.md linked three never-written guide pages as aspirational links - they stay plain text until pages exist HANDS-OFF (project owner, 2026-11-02): docs/user/filters/** and docs/user/searching-and-filtering.md are exempt as link sources so no future checker failure can force edits to the filter documentation. Files linking INTO them remain checked. --- docs/contributing/contributing.md | 6 +- docs/contributing/development.md | 6 +- .../development/calibre-opf-implementation.md | 6 +- docs/index.md | 121 ++++++------------ docs/operations/operations.md | 6 +- docs/user/admin-guide.md | 2 +- docs/user/devices/kobo-setup.md | 2 +- docs/user/frontend-guide.md | 2 +- docs/user/settings-guide.md | 2 +- internal/docs/links_test.go | 43 +++++-- 10 files changed, 85 insertions(+), 111 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 8be501b5..3e264b79 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -4,7 +4,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide ## 🚀 Getting Started -- **[Development Guide](Development.md)** - Development workflow and architecture +- **[Development Guide](development.md)** - Development workflow and architecture - Architecture overview - Directory structure - Local development setup @@ -14,7 +14,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide ## 📋 Project Guidelines -- **[AGENTS.md](../../AGENTS.md)** - Agent/development rules +- **[AGENTS.md](../contributing/contributing.md)** - Development rules and standards live in the Contributing portal - Critical prohibitions - Mandatory requirements - Error recovery protocol @@ -22,7 +22,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide ## 🤝 How to Contribute -We welcome contributions! Please see our [Development Guide](Development.md) for information on: +We welcome contributions! Please see our [Development Guide](development.md) for information on: - Setting up your development environment - Understanding the codebase diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 7dbadab9..3bcfa061 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -510,9 +510,9 @@ DEBUG=true ## 📚 Additional Resources -- [AGENTS.md](../../AGENTS.md) - Agent/development rules -- [API Reference](../API_REFERENCE.md) - Complete API documentation -- [Troubleshooting](../TROUBLESHOOTING.md) - Deployment issues +- [Development rules and standards](contributing.md) - Contributing portal +- [API Reference](../developer/api/api-reference.md) - Split endpoint docs, indexed from its overview +- [Troubleshooting](../operations/troubleshooting.md) - Deployment issues - [Go Documentation](https://go.dev/doc/) - [Echo Framework](https://echo.labstack.com/docs) - [pgx Documentation](https://pgx.github.io/pgx/) diff --git a/docs/development/calibre-opf-implementation.md b/docs/development/calibre-opf-implementation.md index 2010c1fa..7444b360 100644 --- a/docs/development/calibre-opf-implementation.md +++ b/docs/development/calibre-opf-implementation.md @@ -623,6 +623,6 @@ This is a great example of how user feedback can improve implementation design! ## See Also -- [User Guide: Calibre Integration](../../user/calibre-integration.md) -- [Implementation Plan](../../CALIBRE_OPF_IMPLEMENTATION.md) -- [Scanner Source Code](../../internal/services/media_scanner.go) +- [User Guide: Calibre Integration](../user/calibre-integration.md) +- The original implementation plan file was removed from the repo when this page absorbed its content. +- The scanner implementation lives in `internal/services/` (not hyperlinked — the docs site serves only docs). diff --git a/docs/index.md b/docs/index.md index 5751be02..ba14fcd9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. - **Device Setup** - [KOReader Setup Guide](user/devices/koreader-setup.md) - KOReader on Kindle/Kobo/PocketBook hardware - [Kobo Setup Guide](user/devices/kobo-setup.md) - Native Kobo sync (coming soon; use KOReader today) + - [Android App](user/devices/android-app.md) - **Sync Configuration** - [Universal Sync Guide](user/sync-guide.md) - Understanding sync, book matching, conflicts @@ -22,53 +23,51 @@ Complete guide to Bookhoard documentation. Find what you need quickly. - [Filter cookbook](user/filters/cookbook.md) - ready-made recipes, exact clicks - [Every filter field](user/filters/fields.md) - the generated, always-current reference -- **Frontend & Settings** (Coming Soon) - - Frontend Guide - - User Areas Guide - - Settings Guide - - Admin Guide +- **Guides** + - [Reader Guide](user/reader-guide.md) - reading, highlights, notes + - [Library Browsing](user/library-browsing.md) - browsing and searching your library + - [Collections](user/collections.md) - manual and ⚡ smart shelves, books and episodes + - [Dashboard](user/dashboard.md) + - [Themes](user/themes.md) + - [Calibre Integration](user/calibre-integration.md) + - [Settings Guide](user/settings-guide.md) + - [Profile Guide](user/profile-guide.md) + - [Admin Guide](user/admin-guide.md) + - [Frontend Guide](user/frontend-guide.md) ### 👨‍💻 For Developers **[Developer Documentation Portal](developer/development.md)** - Technical documentation & API reference -- **API Documentation** - - [Complete API Reference](developer/api-reference.md) - Monolithic REST API reference (1,300+ lines) - - [Split Endpoint Docs](developer/api/api-reference.md) - Individual endpoint docs - - [Collections API](developer/api/collections/list_collections.md) - Collections management API - - [Admin API](developer/api/admin/) - User management (admin operations) - - [Media Items API](developer/api/media-items/) - Media item operations including bulk operations and downloads - - [Devices API](developer/api/devices/) - Device sync and shelf management - - [Conflicts API](developer/api/conflicts/) - Sync conflict resolution endpoints - - [Queue API](developer/api/queue/) - Sync queue management endpoints - - [Scanner API](developer/api/scanner/) - Library scanning and automated watch mode (admin) - - [KOReader API](developer/api/koreader/) - KOReader sync protocol endpoints - - [Kobo API](developer/api/kobo/) - Kobo sync protocol endpoints (feature coming soon) - - [WebSocket API](developer/api/websocket/) - Real-time sync events +- **API Documentation** — every endpoint is documented individually; the links below are entry points + - [API Reference overview](developer/api/api-reference.md) - index of all endpoint docs + - [Collections API](developer/api/collections/list_collections.md) - collections management API + - [Media Items API](developer/api/media-items/list_media_items.md) - media item operations including bulk operations and downloads + - [Devices API](developer/api/devices/list_devices.md) - Device sync and shelf management + - [Conflicts API](developer/api/conflicts/list_conflicts.md) - Sync conflict resolution endpoints + - [Queue API](developer/api/queue/list_all_queue_items.md) - Sync queue management endpoints + - [Scanner API](developer/api/scanner/overview.md) - Library scanning and automated watch mode (admin) + - [KOReader API](developer/api/koreader/get_library.md) - KOReader sync protocol endpoints + - [Kobo API](developer/api/kobo/sync_from_server.md) - Kobo sync protocol endpoints + - [Admin API](developer/api/admin/list_users.md) - User management (admin operations); content-duplicate cleanup lives in [hash conflicts](developer/api/admin/hash_conflicts_api.md) - **Protocol Specifications** - [KOReader Sync Protocol](developer/api/sync/koreader-protocol.md) - KOReader sync - - [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync (coming soon) - - [WebSocket API](developer/websocket-api.md) - Real-time events + - [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync + +- **Writing UI docs?** Read [Writing UI documentation without screenshots](developer/writing-ui-docs.md) first. ### 🔧 For Operations **[Operations Documentation Portal](operations/operations.md)** - Deployment & maintenance -- **Deployment** - - [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions - -- **Maintenance** (Coming Soon) - - Deployment Guide - - Maintenance Guide - - Monitoring Guide +- [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions ### 🤝 For Contributors **[Contributing Portal](contributing/contributing.md)** - Development workflow -- [Development Guide](contributing/development.md) - Architecture, setup, testing -- [../../AGENTS.md](../../AGENTS.md) - Development rules and standards +- [Development Guide](contributing/development.md) - Architecture, setup, testing, and the project rules --- @@ -76,11 +75,11 @@ Complete guide to Bookhoard documentation. Find what you need quickly. | Want to... | Go to | | -------------------- | ---------------------------------------------------------------------- | -| **Get started** | [README.md](../README.md) - Project overview and quick start | +| **Get started** | [Development Guide](contributing/development.md) - Architecture and quick start | | **Set up a device** | [User Portal → Device Setup](user/user-guide.md) | -| **Use the API** | [Developer Portal → API Docs](developer/development.md) | -| **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md) | -| **Contribute code** | [Contributing Portal → Development Guide](contributing/development.md) | +| **Use the API** | [API Reference overview](developer/api/api-reference.md) | +| **Deploy Bookhoard** | [Operations → Troubleshooting](operations/troubleshooting.md) | +| **Contribute code** | [Development Guide](contributing/development.md) | | **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) | | **Read in the browser** | [User Portal → Web Reader Guide](user/reader-guide.md) | @@ -92,65 +91,25 @@ Complete guide to Bookhoard documentation. Find what you need quickly. | Question | Answer | | --------------------------- | ------------------------------------------------------ | -| ...install Bookhoard? | [README.md](../README.md) - Quick Start | | ...set up KOReader? | [KOReader Setup Guide](user/devices/koreader-setup.md) | | ...use a Kobo? | [Kobo Setup Guide](user/devices/kobo-setup.md) - native sync coming soon; KOReader works today | | ...understand sync? | [Sync Guide](user/sync-guide.md) | | ...read in the browser? | [Web Reader Guide](user/reader-guide.md) - reading, highlights, notes | | ...resolve conflicts? | [Sync Guide](user/sync-guide.md) - Managing Conflicts | | ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) | -| ...use the API? | [API Reference](developer/api-reference.md) | +| ...use the API? | [API Reference overview](developer/api/api-reference.md) | +| ...write UI docs? | [Writing UI documentation](developer/writing-ui-docs.md) | | ...contribute code? | [Development Guide](contributing/development.md) | -### "Where is..." - -| Information | Location | -| ---------------------- | ----------------------------------------------------------- | -| ...features list? | [README.md](../README.md) | -| ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) | -| ...API endpoints? | [API Reference](developer/api-reference.md) | -| ...secrets config? | [.env.example](../.env.example) | -| ...operational config? | [docker-compose.yml](../docker-compose.yml) | -| ...deployment issues? | [Troubleshooting Guide](operations/troubleshooting.md) | - ---- - -## 🎯 Common Workflows - -### Set up a new device - -1. Choose your device: [KOReader](user/devices/koreader-setup.md) (works on Kindle, Kobo, and PocketBook hardware) -2. Understand sync: [Sync Guide](user/sync-guide.md) -3. Troubleshoot: Device-specific guides - -### Integrate with Bookhoard API - -1. Start with [API Reference](developer/api-reference.md) -2. Explore [Collections API](developer/api/collections/list_collections.md) -3. Review [WebSocket API](developer/websocket-api.md) -4. Test with [bruno/](../bruno/) collections - -### Deploy to production - -1. Follow [README.md](../README.md) quick start -2. Configure environment: [.env.example](../.env.example) -3. Review [Troubleshooting Guide](operations/troubleshooting.md) -4. Check [Development Guide](contributing/development.md) for performance tuning - --- ## 📝 Contributing to Documentation When adding new features: -1. **User-facing features** → Update relevant User docs -2. **API endpoints** → Update [API Reference](developer/api-reference.md) & split docs -3. **Backend changes** → Update [Development Guide](contributing/development.md) -4. **Deployment changes** → Update [Operations Portal](operations/operations.md) - -Keep [../../AGENTS.md](../../AGENTS.md) in mind for documentation standards. - ---- - -**Last Updated**: August 2026 -**Bookhoard Version**: 1.0 +1. **User-facing features** → Update the relevant User docs +2. **API endpoints** → Update the endpoint docs under `developer/api/` (start from the [API Reference overview](developer/api/api-reference.md)) +3. **Backend changes** → Update the [Development Guide](contributing/development.md) +4. **Deployment changes** → Update the [Operations Portal](operations/operations.md) +5. **New UI controls in docs** → Add them to the [UI controls glossary](developer/ui-controls.md) +6. **UI appearances in docs** → Follow [Writing UI documentation without screenshots](developer/writing-ui-docs.md) diff --git a/docs/operations/operations.md b/docs/operations/operations.md index 614c0168..63110172 100644 --- a/docs/operations/operations.md +++ b/docs/operations/operations.md @@ -15,19 +15,19 @@ Welcome to the Bookhoard operations documentation. This section contains guides ### Additional Deployment Guides -**[Deployment Guide](deployment.md)** - Comprehensive deployment guide +**Deployment Guide** - Comprehensive deployment guide - _Coming Soon_ ## 🛠️ Maintenance -**[Maintenance Guide](maintenance.md)** - Ongoing operations and maintenance +**Maintenance Guide** - Ongoing operations and maintenance - _Coming Soon_ ## 📊 Monitoring -**[Monitoring Guide](monitoring.md)** - Monitoring and alerting +**Monitoring Guide** - Monitoring and alerting - _Coming Soon_ diff --git a/docs/user/admin-guide.md b/docs/user/admin-guide.md index 5b5ca20e..2bb187fa 100644 --- a/docs/user/admin-guide.md +++ b/docs/user/admin-guide.md @@ -13,4 +13,4 @@ This guide will cover: --- -_In the meantime, check out our [Operations Portal](../operations/)_ +_In the meantime, check out our [Operations Portal](../operations/operations.md)_ diff --git a/docs/user/devices/kobo-setup.md b/docs/user/devices/kobo-setup.md index a3b65865..56f945e9 100644 --- a/docs/user/devices/kobo-setup.md +++ b/docs/user/devices/kobo-setup.md @@ -34,7 +34,7 @@ A: Nothing — KOReader will keep working. Native sync simply adds another optio - [KOReader Setup Guide](koreader-setup.md) — works on Kobo today - [Bookhoard Universal Sync Guide](../sync-guide.md) -- [Bookhoard API Reference](../../developer/api-reference.md) +- Kobo sync protocol (for developers): [Kobo API docs](../../developer/api/kobo/sync_from_server.md) --- diff --git a/docs/user/frontend-guide.md b/docs/user/frontend-guide.md index f897de99..d2da31bb 100644 --- a/docs/user/frontend-guide.md +++ b/docs/user/frontend-guide.md @@ -13,4 +13,4 @@ This guide will cover: --- -_In the meantime, check out our [Device Setup Guides](devices/)_ +_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_ diff --git a/docs/user/settings-guide.md b/docs/user/settings-guide.md index d008fd25..4a2ee24c 100644 --- a/docs/user/settings-guide.md +++ b/docs/user/settings-guide.md @@ -12,4 +12,4 @@ This guide will cover: --- -_In the meantime, check out our [Device Setup Guides](devices/)_ +_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_ diff --git a/internal/docs/links_test.go b/internal/docs/links_test.go index ae5a8557..d41c9ed6 100644 --- a/internal/docs/links_test.go +++ b/internal/docs/links_test.go @@ -8,40 +8,55 @@ import ( "testing" ) -// TestDocsRelativeLinks keeps the developer docs tree internally navigable: -// every relative markdown link must point at a file that exists. The -// api-reference overview once shipped 20+ directory-style links -// (authentication/ etc.) that 404'd — this gate makes that class of rot -// fail make test. (docs/user is excluded: end-user prose has its own pass.) +// TestDocsRelativeLinks keeps every doc tree internally navigable: every +// relative markdown link must point at a file that exists. The api-reference +// overview once shipped 20+ directory-style links (authentication/ etc.) +// that 404'd — this gate makes that class of rot fail make test. // // Rules: // - http(s):, mailto:, and pure #anchors are skipped // - every other target must end in .md and resolve (relative to the -// linking file) to an existing file inside the tree +// linking file) to an existing file inside the docs tree // - directory-style targets ("area/") are the exact bug this test exists // for and always fail +// +// Hands-off sources (project owner instruction, 2026-11-02: DO NOT EDIT THE +// FILTER DOCS): docs/user/filters/** and docs/user/searching-and-filtering.md +// are not scanned as link sources, so no future gate failure can force an +// edit there. Files linking INTO them are still checked — resolution needs +// file existence only, never edits to their content. + var docsLinkRe = regexp.MustCompile(`\[[^\]]*\]\(([^)\s]+)\)`) +var handsOffFilterDocs = []string{ + "user/filters/", + "user/searching-and-filtering.md", +} + func TestDocsRelativeLinks(t *testing.T) { - // Walk developer docs; escape-check against the whole docs tree — - // cross-area links into docs/user are legitimate (same site). - devRoot, err := filepath.Abs("../../docs/developer") - if err != nil { - t.Fatalf("abs developer root: %v", err) - } treeRoot, err := filepath.Abs("../../docs") if err != nil { t.Fatalf("abs docs root: %v", err) } - err = filepath.WalkDir(devRoot, func(path string, d os.DirEntry, err error) error { + err = filepath.WalkDir(treeRoot, func(path string, d os.DirEntry, err error) error { if err != nil || d.IsDir() || !strings.HasSuffix(path, ".md") { return err } + rel, err := filepath.Rel(treeRoot, path) + if err != nil { + return err + } + relSlash := filepath.ToSlash(rel) + for _, off := range handsOffFilterDocs { + if strings.HasPrefix(relSlash, off) { + return nil + } + } + raw, err := os.ReadFile(path) if err != nil { return err } - rel, _ := filepath.Rel(docsRoot, path) absPath, err := filepath.Abs(path) if err != nil { return err