-
Improvement
-
Resolution: Fixed
-
Minor
-
None
-
None
The 'AGL features' handled by aglsetup script at setup time must be documented.
Proposal:
- in each feature or machine folder (example: meta-agl/templates/feature/<feature>) let's add a file named XX_FEATURE.md (or XX_MACHINE.md) with XX being a number between 00 and 99. NB: agl-devel feature has already a markdown file to explain its usage.
-
- XX_FEATURE.md should contain only headings with level >=3 (so that they can be concatenated in a higher level document)
- a front matter block on top of the file can be used to specify some abstract to be reused in aglsetup to get some online help. Example:
--- description: agl-foo enables blablabla author: Alex Terieur <foo@bar.org> --- ## Feature 'agl-foo' Some text to describe things in details.
- then we can modify aglsetup and add an option --doc --to generate a full document to be stored in meta-agl/FEATURES.md. NB: --doc is very close to --help, but output format differs. All individual doc fragments are taken in order (as for local conf or bblayers fragments) and concatenated in specified ordering.
One issue with this process: the full documentation is located in meta-agl but the features can be spread in many different layers. So when changing a feature in meta-agl-demo, we'll have to update meta-agl too. Not perfect, but acceptable as features don't change very often.
# | Subject | Branch | Project | Status | CR | V |
---|---|---|---|---|---|---|
18111,1 | templates/*: add documentation for features | master | AGL/meta-agl-extra | Status: MERGED | +2 | +1 |
18113,6 | add markdown documentation for all machines and features | master | AGL/meta-agl | Status: MERGED | +2 | +1 |
18115,5 | add markdown documentation for all machines and features | master | AGL/meta-agl-demo | Status: MERGED | +2 | +1 |
18117,5 | add markdown documentation for all machines and features | master | AGL/meta-agl-devel | Status: MERGED | +2 | +1 |
21893,1 | add markdown documentation for all machines and features | master | AGL/meta-agl-extra | Status: MERGED | +2 | +1 |
22033,2 | machine: Add readme for ebisu | master | AGL/meta-agl | Status: MERGED | +2 | +1 |
22108,1 | machine: Add readme for ebisu | halibut | AGL/meta-agl | Status: MERGED | +2 | +1 |
28610,3 | Updating AGL feature | octopus | AGL/documentation | Status: MERGED | +2 | +1 |
28624,3 | Updating AGL feature | master | AGL/documentation | Status: MERGED | +2 | +1 |
28628,2 | documentation: fix typo | master | AGL/documentation | Status: MERGED | +2 | +1 |