Uploaded image for project: ' AGL Development'
  1. AGL Development
  2. SPEC-1902

aglsetup features must be documented individually

    XMLWordPrintable

    Details

      Description

      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.

        Attachments

        # Subject Branch Project Status CR V

          Activity

            People

            Assignee:
            Unassigned
            Reporter:
            sdesneux Stéphane Desneux
            Votes:
            0 Vote for this issue
            Watchers:
            6 Start watching this issue

              Dates

              Created:
              Updated: