Merge pull request #91 from aliceinwire/configuration

docs/config: Add config subcommand configuration
kernelci · Jan 19, 2025 · 3acdfd9 · 3acdfd9
2 parents a3471ac + 4a90085
commit 3acdfd9
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 31 deletions.
diff --git a/docs/_index.md b/docs/_index.md
@@ -49,39 +49,18 @@ poetry run kci-dev <options>
 
 > Configuration is only necessary if you are using any of the Maestro Commands listed in the Maestro section.
 
-kci-dev searches for and loads a configuration file in the following order of priority:
-1) The global configuration file located at /etc/kci-dev.toml.
-2) The user-specific configuration file at ~/.config/kci-dev/kci-dev.toml
-3) A site-specific configuration file, which is .kci-dev.toml by default, but can be overridden with the --settings option. 
-
-Priority: The configuration files are loaded in the order listed above, with each subsequent file overriding the settings from the previous one.  
-If a user-specific file is present, it will override the global configuration.  
-The site-specific file, whether default or specified by --settings, takes precedence over both the global and user-specific configuration files.  
-
-```toml
-default_instance="local"
-
-[local]
-pipeline="https://127.0.0.1"
-api="https://127.0.0.1:8001/"
-token="example"
-
-[staging]
-pipeline="https://staging.kernelci.org:9100/"
-api="https://staging.kernelci.org:9000/"
-token="example"
-
-[production]
-pipeline="https://kernelci-pipeline.westus3.cloudapp.azure.com/"
-api="https://kernelci-api.westus3.cloudapp.azure.com/"
-token="example"
+The following command will create a config file template under `~/.config/kci-dev/kci-dev.toml`   
+
+```sh
+kci-dev config
 ```
 
-Where `default_instance` is the default instance to use, if not provided in the command line.  
-In section `local`, `staging`, `production` you can provide the host for the pipeline, api and also a token for the available instances.  
-pipeline is the URL of the KernelCI Pipeline API endpoint, api is the URL of the new KernelCI API endpoint, and token is the API token to use for authentication.  
-If you are using KernelCI Pipeline instance, you can get the token from the project maintainers.  
-If it is a local instance, you can generate your token using [kernelci-pipeline/tools/jwt_generator.py](https://github.com/kernelci/kernelci-pipeline/blob/main/tools/jwt_generator.py) script.  
+For more explanation about [`kci-dev config`](config)  
+For more explantiion about the [config file](config_file)
+
+### Config file parameters
+
+Config file `kci-dev.toml` parameters and example can be seen [here](config_file)
 
 ### Configuration options
 
@@ -112,6 +91,10 @@ Pull results from the Dashboard. See detailed [documentation](results).
 
 #### checkout
 
+- [config](config)
+
+#### checkout
+
 - [checkout](checkout)
 
 #### testretry

diff --git a/docs/config.md b/docs/config.md
@@ -0,0 +1,42 @@
++++
+title = 'config'
+date = 2025-01-18T15:43:18+08:00
+description = 'Config tool for creating a config file template.'
++++
+
+`kci-dev config` is a config tool for creating a config file template.
+This command is needed when no configuration is present.
+
+### kci-dev config
+
+`kci-dev config` without arguments will check for config file,  
+if none are found will create a config file template by default to  
+`~/config/kci-dev/kci-dev.toml`    
+
+## Base parameters
+
+### --file-path
+
+Optional file path for creating a config file,   
+if none is provided `~/config/kci-dev/kci-dev.toml` is used.   
+
+## Example
+
+### kci-dev config
+
+Example:
+
+```sh
+$ kci-dev config
+Config file not present, adding a config file to ~/.config/kci-dev/kci-dev.toml
+```
+
+### kci-dev config --file-path
+
+Example:
+
+```sh
+$ kci-dev config --file-path ~/test/test.toml
+Config file not present, adding a config file to ~/test/test.toml
+```
+
diff --git a/docs/config_file.md b/docs/config_file.md
@@ -0,0 +1,44 @@
++++
+title = 'config_file'
+date = 2025-01-18T15:54:07+09:00
+description = 'Config file template and parameters.'
++++
+
+## Configuration
+
+> Configuration is only necessary if you are using any of the Maestro Commands listed in the Maestro section.
+
+kci-dev searches for and loads a configuration file in the following order of priority:
+1) The global configuration file located at /etc/kci-dev.toml.
+2) The user-specific configuration file at ~/.config/kci-dev/kci-dev.toml
+3) A site-specific configuration file, which is .kci-dev.toml by default, but can be overridden with the --settings option. 
+
+Priority: The configuration files are loaded in the order listed above, with each subsequent file overriding the settings from the previous one.  
+If a user-specific file is present, it will override the global configuration.  
+The site-specific file, whether default or specified by --settings, takes precedence over both the global and user-specific configuration files.  
+
+```toml
+default_instance="local"
+
+[local]
+pipeline="https://127.0.0.1"
+api="https://127.0.0.1:8001/"
+token="example"
+
+[staging]
+pipeline="https://staging.kernelci.org:9100/"
+api="https://staging.kernelci.org:9000/"
+token="example"
+
+[production]
+pipeline="https://kernelci-pipeline.westus3.cloudapp.azure.com/"
+api="https://kernelci-api.westus3.cloudapp.azure.com/"
+token="example"
+```
+
+Where `default_instance` is the default instance to use, if not provided in the command line.  
+In section `local`, `staging`, `production` you can provide the host for the pipeline, api and also a token for the available instances.  
+pipeline is the URL of the KernelCI Pipeline API endpoint, api is the URL of the new KernelCI API endpoint, and token is the API token to use for authentication.  
+If you are using KernelCI Pipeline instance, you can get the token from the project maintainers.  
+If it is a local instance, you can generate your token using [kernelci-pipeline/tools/jwt_generator.py](https://github.com/kernelci/kernelci-pipeline/blob/main/tools/jwt_generator.py) script.  
+