docs: initial skeleton #6
Conversation
This commit adds a skeleton of the documentation based on docs starter pack: https://canonical-starter-pack.readthedocs-hosted.com/latest/. Note that the docs themselves are not updated. Only necessary files and hacks are introduced in this commit.
Read reuse/substitutions.yaml if it exists into myst_substitutions to reuse content with simple markdown. Additionally, delete reuse/links.txt since we are not using reStructuredText. This commit also updates a few misc settings in conf.py.
Update the site landing page (/) at docs/index.md with a summary of Chisel and proper links to different sections. This commit also creates a few placeholder files and directories for later use, e.g. reference/, how-to/index.md etc.
Mostly copied from the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/stable/explanation/chisel/#package-slices
Additionally add placeholder CLI commands reference pages.
This commit adds reference pages for all Chisel subcommands.
cjdcordeiro
left a comment
cjdcordeiro
left a comment
There was a problem hiding this comment.
1st pass: addressing the index page only
This reverts commit b69bbea.
rebornplusplus
requested review from
cjdcordeiro and
letFunny
and removed request for
cjdcordeiro
letFunny
left a comment
letFunny
left a comment
There was a problem hiding this comment.
First pass, thanks for this Rafid and Cris! Apart from my comments, I am missing two main things:
- Talking about the release validation that happens prior to downloading the packages. If we can explain the rationale behind our validation and conflict resolution then users will have a much better intuition on what to expect using different combinations of fields.
- The format in the manifest that is explicitly tailored towards not having to read it all into memory at once and parse it. This is optional and could be done at a later PR.
docs/reference/manifest.md
Outdated
|
|
||
| The uncompressed manifest is a "jsonwall" file. This is a custom database file | ||
| format where there is one JSON object per line, and both the individual JSON | ||
| fields and the lines themselves (except the |
There was a problem hiding this comment.
This is not true, the lines are sorted according to the ordering of the fields in the struct and we define it manually so the fields that we want to use as indexes appear first.
There was a problem hiding this comment.
Indeed. I've rephrased it. Pls double check 75406e1
There was a problem hiding this comment.
I think I was not super clear in my previous comment. What I meant is that for one line, the contents of the struct, e.g. {kind: path, mode: ...} are ordered based on the ordering of the struct in the code, we define that based on the fields that we want to index. However, the file as a whole is ordered lexicographically so you can do binary search. That is, once you have all the lines, each one of them having the fields ordering defined in their respective struct, we sort all the lines to then output it as the jsonwall file (the lines are unchanged but their position in the file is sorted).
There was a problem hiding this comment.
But isn't that what the current text currently says? I.e. I'm not being specific about the struct-based JSON ordering, but I mentioned that the whole list is sorted (according to kind - which, because of the struct-based ordering, is always the 1st field)
|
Thanks @letFunny . I put those two "misses" as next-step tasks in our docs Epic. Addressed all the others. I'll now raise the 1st PR in chisel, just with the Sphinx stuff, and then the 2nd one. unless you have further fundamental comments, feel free to review other nits in the upstream repo. |
This PR adds the initial docs in Chisel as a baseline.
This PR covers the sections described in the RK045 spec.