also add a glossary and begin to use it in the getting-started page
Details
Details
Diff Detail
Diff Detail
- Repository
- rDDOC Development documentation
- Branch
- d668
- Lint
No Linters Available - Unit
No Unit Test Coverage - Build Status
Buildable 2526 Build 3133: arc lint + arc unit
Event Timeline
Comment Actions
What do the pipe in |swh| mean?
Regarding docs/images/general-architecture.svg: I really like it. Could you add the names of involved technologies (eg. in a box with logo->name matching) so they are easier to search later on?
Regarding mermaid graphs: The text is too small to read without zooming in. Increasing the font size should fix that without breaking the layout.
| docs/architecture.rst | ||
|---|---|---|
| 8 | Missing a closing parenthesis. | |
| 40 | and inserts nodes and edges in the graph. | |
| 65 | "seauence" | |
| 73 | "gitlba" | |
| docs/glossary.rst | ||
| 33 | maybe explain the difference between a SHA1 and “git-like” SHA1 in that glossary as well? | |
| docs/glossary.rst | ||
|---|---|---|
| 137 | Don't forget this :) | |
Comment Actions
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-references
Looks like the substitutions file is missing?
Comment Actions
Several modifications
Summary:
- replace mermaid with plantuml
- use sphinxcontrib.images
- better glossary
Comment Actions
Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))
Comment Actions
I've seen this. Ok to deprecate it ASA this diff is published and the doc is online.
In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.
Comment Actions
Agreed.
I think we can walk the fine line between a glossary (short definition, for mnemonic use) v. definition (long definition, with all the details). The Data Model can very well be the source for the latter; the glossary for the former. And for each of the relevant entries the glossary can link to the Data Model under a "for more information see [...]" notice.