docs: frame hexol as a substrate; add oslo-config bootstrap example#2
Closed
polyedre wants to merge 1 commit into
Closed
docs: frame hexol as a substrate; add oslo-config bootstrap example#2polyedre wants to merge 1 commit into
polyedre wants to merge 1 commit into
Conversation
Make the core philosophy explicit and discoverable: hexol ships an engine, and users are expected to bootstrap a thin domain layer (a renderer via renders-with + constructs via define-construct) for their target. A prior reviewer read 'no oslo.config renderer, no OpenStack vocabulary' as a shortcoming because the docs never framed that thin-layer bootstrap as the intended first step. Framing added: - README: new 'The shape' section near the top — the kernel -> generic renderers -> your thin domain layer -> your inventory layering, with the renders-with (kernel.scm:484) / define-construct hooks and sql.scm / ledger.scm / oslo-config.scm as minimal worked examples. - docs/extending.md: new 'hexol is a substrate' section walking the oslo-config bootstrap (renderer + config-section/keystone-authtoken constructs) as the normal first step. New example: - examples/oslo-config.scm — the whole bootstrap in one file: an oslo.config INI renderer + a service vocabulary, ~40 lines. Renders via 'hexol render -o ini'. Doc-bug fixes (docs must match repo): - examples/regions.scm was referenced but missing. Created it as the importable region-table module the docs describe; inventory.scm now imports it (render output unchanged). - Dropped the authoring.md repository-layout block for the CMDB subsystem, deleted in the parent commit (cmdb/, bin/cmdb-server, docs/cmdb.md, …). Docs-only: no library code or real target library changed. Tests pass; inventory.scm and oslo-config.scm both render.
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
1 participant
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.
Docs-only. Reframes hexol's "no oslo.config renderer / no OpenStack vocabulary" from a shortcoming into the intended design: you bootstrap a thin domain layer, and that's step one.
Framing added
renders-withhook (hexol/kernel.scm:484) anddefine-construct.examples/oslo-config.scm.New example (renders)
renders-with, plusconfig-sectionandkeystone-authtokenconstructs.hexol render -o iniemits correct INI;tree/render(sexp) work for free.Doc-bug fixes (docs ↔ repo consistency)
examples/regions.scmwas referenced indocs/authoring.mdbut did not exist → created as the importable region module;examples/inventory.scmnow imports it (render output byte-identical).Verification
guix shell -m manifest.scm -- make test→ all checks passed.hexol render -o ini -i examples/oslo-config.scm→ correct INI.hexol render -i examples/inventory.scm→ identical to pre-change baseline.