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.

Mar 11 '24 06:03 didierjoomun

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 https://github.com/armbian/build/pull/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.

Mar 11 '24 07:03 igorpecovnik

Should ARTIFACT_IGNORE_CACHE and GIT_KERNEL also be in here?

Mar 11 '24 09:03 EvilOlaf

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.

Mar 11 '24 09:03 igorpecovnik

record and mark deprecated or just drop them

I wasn't aware that those are deprecated?

Mar 11 '24 12:03 EvilOlaf

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 ...

Mar 11 '24 13:03 igorpecovnik

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.

Mar 12 '24 05:03 EvilOlaf

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.

Mar 12 '24 21:03 rpardini

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 https://github.com/armbian/build/pull/5734#issuecomment-1734954337

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" ]

Mar 13 '24 09:03 Tearran

@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!

Mar 13 '24 09:03 didierjoomun

Centralize feature documentation

Description