docs: publish architecture documentation via mdBook and GitHub Pages (closes #28) - #29
Merged
Merged
Conversation
…ndored mermaid.min.js
…d from SUMMARY.md, README.md, or roadmap.md
…drop exact dependency versions and benchmark numbers in favor of Cargo.toml, document the test_tlsh data file index trap, and fix the example repo path
…e dead link to atributos-calidad.md, trim the struct snippet and dependency example to their stable parts
…C to the Hnsw/Apotheosis signatures, document the public initialize method
…he hardcoded ef_search default
…e 5.4 reference to 5.3
The documentation was written in July and reviewed against the code of that moment. Meanwhile reverseame#24 (distance type in the dump/load header), reverseame#25 (GEXF export extracted to export::gexf, gexf fork emits the attribute schema), reverseame#27 (record constructors return Result) and reverseame#31 (facade read accessors) landed. Update the interface document, the three views, the glossary and the README accordingly. Text only; the C&C component model and diagrams are untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Views and Beyond documentation (
docs/architecture/: roadmap, quality attributes, directory, module/C&C/deployment views) exists only as plain markdown in the repo, plus a manually maintained copy on the university MediaWiki (valhalla.unizar.es). The wiki copy has already drifted from the source at least once, and nothing renders the mermaid diagrams or cross-links between documents as a browsable site.Changes
docs/book.toml: mdBook config,src = "architecture"(no files moved), title/authors,git-repository-urlandedit-url-templateso each page links back to its source file.docs/architecture/SUMMARY.md: navigation, listing the existing README, the three cross-cutting documents, and the three views. No content rewritten to fit it.docs/mermaid.min.jsanddocs/mermaid-init.js: committed rather than generated in CI, since the deploy workflow only runsmdbook build, notmdbook-mermaid install. Without them the three diagrams would silently fail to render on the published site..github/workflows/pages.yml: builds and deploys on push toapotheosis2(notmain) whendocs/**changes, or viaworkflow_dispatch. Downloads pinned prebuiltmdbook/mdbook-mermaidbinaries instead ofcargo install, to avoid pulling a full Rust toolchain just to build docs..gitignore: addeddocs/book/, the generated output, never committed..gitkeepwere redundant. Renamed, deduplicated, updated the three affected references invista-cc.md/vista-modulos.md.hnsw/radix/recordsdocumented aspub(now private, [Enhancement] Make Apotheosis internal fields private to protect the synchrony invariant #14),HEURISTICdocumented as unvalidated indump/load(now validated, [Bug] dump() does not encode HEURISTIC in file header #10), empty-indexsearch()documented as panicking (now returnsvec![], [Bug] search() panics on empty index #8), and the radix fast-path documented as ignoringkand returning unsorted results (now sorts and truncates toklike the ANN path, [Bug] search() ignores parameter k on radix fast-path #9). Corrected all four.Test plan
Verified locally:
mdbook build docssucceeds with no warnings, all internal links resolve, mermaid diagrams render, and the site was reviewed end to end withmdbook serve.After merging, two one-time repository settings are needed for the site to go live: enable Pages with source set to GitHub Actions, and allow the
apotheosis2branch to deploy under thegithub-pagesenvironment's protection rules.What to do with the existing valhalla.unizar.es mirror is intentionally out of scope here; that involves university infrastructure outside this repo and will be proposed separately once Pages is confirmed working.
Closes #28.