Centralize feature documentation

[didierjoomun]

Description

This is a sample JSON file that can be used to track features and well as their documentation. This will help bridge information between the developers and the technical writers and help maintain up-to-date documentation.

[igorpecovnik]

To add more context here. Idea is to have JSON with instructions how to build and also as an online help (./compile.sh help / --help) A parts from #5894 can probably be used to come up with a function that will render this JSON in some usable way. Current data is also not fully accurate or complete. If anyone thinks this path is bad, further suggestions are more then welcome. Its easier to change directions now. In any case, we have to deal with the content at the same time https://github.com/armbian/documentation Changes / improvements / adding there is also important.

[EvilOlaf]

Should ARTIFACT_IGNORE_CACHE and GIT_KERNEL also be in here?

[igorpecovnik]

Should ARTIFACT_IGNORE_CACHE and GIT_KERNEL also be in here?

We have two choices here - record and mark deprecated or just drop them. Also we need to help Didier supplying this and other information as he doesn't have in-deep know-how about framework. He can pick it up from some draft / raw instructions. We have to help him here.

[EvilOlaf]

record and mark deprecated or just drop them

I wasn't aware that those are deprecated?

[igorpecovnik]

I wasn't aware that those are deprecated?

Actually I am also not sure anymore ... without looking into the code. We need to build this JSON as source of truth ...

[EvilOlaf]

My best guess is they are not deprecated.
Anyway.

By default the build script checks if a specific kernel or uboot package in the configuration which is going to be built (this particular version with this particular patches and this particular configuration) already exists pre-built as artifact and will use it to speed up the build process. ARTIFACT_IGNORE_CACHE will prevent this and force building from source.

KERNEL_GIT (or was it GIT_KERNEL? I cannot remember) allows to force downloading the full Linux kernel tree or just a shallow copy of the major version that is going to be built. By default the script decides by the available hard drive space.

[rpardini]

• BUILD_ONLY: doesnt exist at all
• KERNEL_ONLY: doesnt exist at all
• KERNEL_CONFIGURE: deprecated (use kernel-config command instead)
• REPOSITORY_INSTALL: doesnt exist at all

... and I stopped reviewing, sorry.

@didierjoomun where did you get this list? What is the objective here with this "json"?

Just to clarify, when months/year ago I suggested the metadata format, the intention was to stop duplicating information between the codebase and the documentation, by having a common descriptor that is then used to generate both the code and the documentation.

A very early example/tentative still lives https://github.com/rpardini/armbian-build/blob/extensions/config/cmdline-params.yaml -- maybe we can work from that.

[Tearran]

Just to clarify, when months/year ago I suggested the metadata format, the intention was to stop duplicating information between the codebase and the documentation, by having a common descriptor that is then used to generate both the code and the documentation. https://github.com/rpardini/armbian-build/blob/extensions/config/cmdline-params.yaml

@rpardini #5734 (comment)

A very early example/tentative still lives https://github.com/rpardini/armbian-build/blob/extensions/config/cmdline-params.yaml -- maybe we can work from that.

This level of nesting, rabbit hole, not family friendly in a manner of speaking :) but here goes

  commands:
    # @TODO: describe all commands here, and _generate_ lib/functions/cli/commands.sh
    "build":
      preferred: build
      aliases: [ "image" ]
      description: "Build a complete Armbian image"
      default: true # this is the default CLI command run when no command is specified
      bash-handler: "standard_build"

Perhaps the naming conventions helps assumed key pairs to layout as

{
    "cli": {
        "commands": {
            "build": {
                "preferred": "build",
                "aliases": [
                    "image"
                ],
                "description": "Build a complete Armbian image",
                "default": true,
                "bash-handler": "standard_build"
            }
        }
    }
}

Hoping that all of build are commands and use

{
    "cli": {
        "build": {
            "preferred": "build",
            "aliases": [
                "image"
            ],
            "description": "Build a complete Armbian image",
            "default": true,
            "bash-handler": "standard_build"
        }
    }
}

with this PR could easily Translates, convert, change.

cli:
  commands:
    # @TODO: describe all commands here, and _generate_ lib/functions/cli/commands.sh
    "build":
      preferred: build
      aliases: [ "image" ]
      description: "Build a complete Armbian image"
      default: true # this is the default CLI command run when no command is specified
      bash-handler: "standard_build"

"Main_options": {
      "BUILD_ONLY": {
        "Author": "xx",
        "src_reference": "xx",
        "desc": "Defines what artifacts should be built",
        "example / [note] test case": "./compile.sh BUILD_ONLY=u-boot,kernel,armbian-config",
        "status": "active",
        "doc_link": ""
      },

    "cli": {
      "build": {
        "Author": "",
        "src_reference": "",
        "desc": "Build a complete Armbian image",
        "example:"standard_build [missing details]",
        "status": "unknown",
        "doc_link": ""
      }

And expost the elitive information.

do you have room for in your mix?

        "doc_link": ""
         "Author": "",
        "src_reference": "",

What is the cool and ominus named pair, aculay do you see a place in the existing key : pair in this PR I can see use for short name but as easily see personalization

aliases: [ "image" ]

[didierjoomun]

@didierjoomun where did you get this list? What is the objective here with this "json"?

Hi @rpardini,
This JSON has been created from the actual documentation: https://docs.armbian.com/Developer-Guide_Build-Options/
As discussed in the last documentation meeting, we wanted to create a document that would hold enough information for me to write the documentation on features, etc. We took the actual documentation so that we can remove or add elements from it.

The goal of the document is to have a single source of truth of features/options present in the build framework with their description so that I can write/update the documentation.

Just to clarify, when months/year ago I suggested the metadata format, the intention was to stop duplicating information between the codebase and the documentation, by having a common descriptor that is then used to generate both the code and the documentation.

Thank you for clarifying, I think we are aligned. However, I doubt that we can generate a full documentation based on the metadata, unless it contains the whole documentation.

A very early example/tentative still lives https://github.com/rpardini/armbian-build/blob/extensions/config/cmdline-params.yaml -- maybe we can work from that.

Sure, we can work from that! What I need, as a technical writer, is to know the status of features/ options, and have enough information about them so that I can write the documentation, whether it be tutorials, how-tos, references, or explanations. From the last documentation meeting, I understood that right now, we don't have a single source of truth that I can consult.

I hope it clarifies my PR. Let me know if you need any other infos! The next documentation meeting is on Friday 15th March.
Thank you!