Skip to content

Migrate Documentation to Great Docs (GSI-2478)#239

Open
Cito wants to merge 19 commits into
mainfrom
feature/migrate-to-great-docs-gsi-2478
Open

Migrate Documentation to Great Docs (GSI-2478)#239
Cito wants to merge 19 commits into
mainfrom
feature/migrate-to-great-docs-gsi-2478

Conversation

@Cito

@Cito Cito commented Jul 3, 2026

Copy link
Copy Markdown
Member

Replaces the MkDocs setup with Great Docs (Quarto-based) and fills in the previously missing DAO documentation.

Docs migration (GSI-2478)

  • Swap mkdocs.yml for great-docs.yml; move narrative docs from docs/*.md to user_guide/*.qmd at the repo root
  • Promote the README to the docs landing page and drop the old README generation step
  • Auto-generate the API reference from docstrings; update the publish_docs workflow, devcontainer, and locked dependencies accordingly
  • Two pre-render hooks work around current Great Docs limitations (0.14.1): fix_source_link_paths.py restores the src/ prefix in "view source" links, and add_member_anchor_ids.py adds the qualified anchors that API cross-links point to. Both carry TODOs to remove once fixed upstream.

New DAO documentation (GSI-2157)

  • The DAO Pattern — concept, trade-offs, and its place in the Triple Hexagonal Architecture
  • Data Access Objects — the Dao / DaoFactoryProtocol interfaces, CRUD/find semantics, error model, and a worked custom-provider example
  • MongoDB DAO — configuration, queries and filters, indexes, and error handling

All code snippets were executed against the library; the MongoDB examples were verified end-to-end against a real MongoDB container.

Docstring & tooling fixes

  • Correct outdated find-mapping docstrings (UUIDs/datetimes are matched natively, not as strings) and tidy a few Raises: blocks for Google-style parsing
  • Consolidate the cSpell dictionary into .vscode/settings.json and scope the Markdown formatter to [markdown]

@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 28678923638

Coverage remained the same at 93.281%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 3944
Covered Lines: 3679
Line Coverage: 93.28%
Coverage Strength: 0.93 hits per line

💛 - Coveralls

@Cito Cito requested a review from TheByronHimes July 7, 2026 08:40

@TheByronHimes TheByronHimes left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks much nicer than mkdocs.
However, when I clicked User Guide at the top of the page it took me to the old MkDocs site. Is that just me or does that need to be fixed?

The DAO sections were nice - I think they convey the info intuitively and cover everything with appropriate volume.

@Cito

Cito commented Jul 9, 2026

Copy link
Copy Markdown
Member Author

It's not yet deployed to GitHub pages, that happens only when we merge to main.

But you can great-docs build and great-docs preview locally.

@TheByronHimes

Copy link
Copy Markdown
Member

That's how I was testing it out

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants