diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0da1341..e132d3e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -45,4 +45,5 @@ repos: files: "docs\/.+rst$" additional_dependencies: - sphinx-argparse + - sphinx-tabs - sphinxcontrib-mermaid diff --git a/docs/conf_common.py b/docs/conf_common.py index 7e6e853..6624373 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -30,6 +30,7 @@ 'myst_parser', 'sphinxcontrib.mermaid', 'sphinxarg.ext', + 'sphinx_tabs.tabs', ] templates_path = ['_templates'] diff --git a/docs/en/references/config_file.md b/docs/en/references/config_file.md deleted file mode 100644 index a97f279..0000000 --- a/docs/en/references/config_file.md +++ /dev/null @@ -1,78 +0,0 @@ -# Configuration File `.idf_build_apps.toml` - -There are many CLI options available for `idf-build-apps`. While these options provide usage flexibility, they also make the CLI command too long and difficult to read. However, a configuration file allows defining all these options in a more readable and maintainable way. - -## Where `idf-build-apps` Looks for the file - -When using `idf-build-apps` within a Python project, it is recommended to use `pyproject.toml` as the configuration file, as defined by [PEP 518][pep-518]. This file is written in [TOML][toml], a widely used configuration file language. As of Python 3.11, the standard library includes native support for [TOML][toml]. - -When running `idf-build-apps`, it looks for `pyproject.toml` starting from the current directory. If the file is not found, it searches parent directories until it either finds the file, encounters a `.git` directory, or reaches the root of the file system. - -Alternatively, `idf-build-apps` will also look for a file named `.idf_build_apps.toml`, which is recommended for use in non-Python projects. - -Besides, you may also specify the configuration file path using the `--config-file ` CLI option. - -## Usage - -You may define it in `.idf_build_apps.toml`: - -```toml -paths = [ - "components", - "examples", -] -target = "esp32" -recursive = true - -# config rules -config = [ - "sdkconfig.*=", - "=default", -] - -# build related options -build_dir = "build_@t_@w" -``` - -Or in `pyproject.toml` with `[tool.idf-build-apps]` section: - -```toml -[tool.idf-build-apps] -# same content -# ... -``` - -Running `idf-build-apps build` with any of the configuration methods mentioned is equivalent to the following CLI command: - -```shell -idf-build-app build \ - --paths components examples \ - --target esp32 \ - --recursive \ - --config "sdkconfig.*=" --config "=default" \ - --build-dir "build_@t_@w" -``` - -[TOML][toml] supports native data types. In order to get the config name and type of the corresponding CLI option, you may refer to the help messages by using `idf-build-apps find -h` or `idf-build-apps build -h`. - -For instance, the `--paths` CLI option help message shows: - -```text --p PATHS [PATHS ...], --paths PATHS [PATHS ...] - One or more paths to look for apps. - - default: None - - config name: paths - - config type: list[str] -``` - -This indicates that in the configuration file, you should specify it with the name `paths`, and the type should be a "list of strings". - -```toml -paths = [ - "foo", - "bar", -] -``` - -[toml]: https://toml.io/en/ -[pep-518]: https://www.python.org/dev/peps/pep-0518/ diff --git a/docs/en/references/config_file.rst b/docs/en/references/config_file.rst new file mode 100644 index 0000000..43a61f1 --- /dev/null +++ b/docs/en/references/config_file.rst @@ -0,0 +1,162 @@ +############################################# + Configuration File ``.idf_build_apps.toml`` +############################################# + +There are many CLI options available for ``idf-build-apps``. While these options provide usage flexibility, they also make the CLI command too long and difficult to read. However, a configuration file allows defining all these options in a more readable and maintainable way. + +*********************** + Config File Discovery +*********************** + +``idf-build-apps`` supports a few ways to specify the configuration file (in order of precedence): + +- specify via CLI argument ``--config-file `` +- ``.idf_build_apps.toml`` in the current directory +- ``.idf_build_apps.toml`` in the parent directories, until it reaches the root of the file system +- ``pyproject.toml`` with ``[tool.idf-build-apps]`` section +- ``pyproject.toml`` in the parent directories, until it reaches the root of the file system + +******* + Usage +******* + +We recommend using the ``.idf_build_apps.toml`` file for non-Python projects and the ``pyproject.toml`` file for Python projects. When using the ``pyproject.toml`` file, define the configuration options in the ``[tool.idf-build-apps]`` section. + +Here's a simple example of a configuration file: + +.. tabs:: + + .. group-tab:: + + ``.idf_build_apps.toml`` + + .. code:: toml + + paths = [ + "components", + "examples", + ] + target = "esp32" + recursive = true + + # config rules + config = [ + "sdkconfig.*=", + "=default", + ] + + .. group-tab:: + + ``pyproject.toml`` + + .. code:: toml + + [tool.idf-build-apps] + paths = [ + "components", + "examples", + ] + target = "esp32" + recursive = true + + # config rules + config = [ + "sdkconfig.*=", + "=default", + ] + +Running ``idf-build-apps build`` with the above configuration is equivalent to the following CLI command: + +.. code:: shell + + idf-build-app build \ + --paths components examples \ + --target esp32 \ + --recursive \ + --config-rules "sdkconfig.*=" "=default" \ + --build-dir "build_@t_@w" + +`TOML `__ supports native data types. In order to get the config name and type of the corresponding CLI option, you may refer to the help messages by using ``idf-build-apps find -h`` or ``idf-build-apps build -h``. + +For instance, the ``--paths`` CLI option help message shows: + +.. code:: text + + -p PATHS [PATHS ...], --paths PATHS [PATHS ...] + One or more paths to look for apps. + - default: None + - config name: paths + - config type: list[str] + +This indicates that in the configuration file, you should specify it with the name ``paths``, and the type should be a “list of strings”. + +.. code:: toml + + paths = [ + "foo", + "bar", + ] + +************************* + CLI Argument Precedence +************************* + +CLI arguments take precedence over the configuration file. This helps to override the configuration file settings when required. + +For example, if the configuration file has the following content: + +.. tabs:: + + .. group-tab:: + + ``.idf_build_apps.toml`` + + .. code:: toml + + target = "esp32" + config_rules = [ + "sdkconfig.*=", + "=default", + ] + + .. group-tab:: + + ``pyproject.toml`` + + .. code:: toml + + [tool.idf-build-apps] + target = "esp32" + config_rules = [ + "sdkconfig.*=", + "=default", + ] + +Override String Configuration +============================= + +To override the ``str`` type configuration, (e.g., ``target``), you can pass the CLI argument directly: + +.. code:: shell + + idf-build-apps build --target esp32s2 + +Override List Configuration +=========================== + +To override the ``list[str]`` type configuration, (e.g., ``config_rules``), you can override it by passing the CLI argument. For example: + +.. code:: shell + + idf-build-apps build --config-rules "foo=bar" + +Or you can unset the configuration by passing an empty string: + +.. code:: shell + + idf-build-apps build --config-rules "" + +Override Boolean Configuration +============================== + +Not supported yet. diff --git a/pyproject.toml b/pyproject.toml index 97c232c..8a131a1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,6 +47,7 @@ doc = [ "myst-parser", # markdown support "sphinxcontrib-mermaid", # mermaid graph support "sphinx-argparse", # auto-generate cli help message + "sphinx-tabs", # tabs ] [project.urls]