chore: update documentation for operations

eclipse-csi · Oct 29, 2024 · 10a2a30 · 10a2a30
1 parent 7d187d4
commit 10a2a30
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 18 deletions.
diff --git a/docs/reference/operations/apply.md b/docs/reference/operations/apply.md
@@ -2,30 +2,31 @@ The `apply` operation will apply changes of the local configuration to the curre
 
 When the `apply` operation is executed, the following happens:
 
-- first the local configuration is [validated](validate.md)
+- the local configuration is [validated](validate.md)
 - the current live configuration is retrieved
 - the current changes are [planned](plan.md)
 - if approved, the changes are applied
 
 !!! note
 
-    In general, resources that are present on GitHub but not contained in the local configuration would be marked
+    In general, resources that are present on GitHub but not contained in the local configuration are marked
     for deletion, however, by default `otterdog` will not remove any resources unless the option `--delete-resources`
     has been specified.
 
 ## Options
 
 ```shell
+  --local                 work in local mode, not updating the referenced default config
   -c, --config FILE       configuration file to use  [default: otterdog.json]
+  -v, --verbose           enable verbose output (-vvv for more verbose output)
   -f, --force             skips interactive approvals
   -n, --no-web-ui         skip settings retrieved via web ui
+  --repo-filter TEXT      a valid shell pattern to match repository names to be included  [default: *]
   --update-webhooks       updates webhook with secrets regardless of changes
-  --update-secrets        updates webhook with secrets regardless of changes
+  --update-secrets        updates secrets regardless of changes
+  --update-filter TEXT    a valid shell pattern to match webhook urls / secret names to be included for update
+                          [default: *]
   -d, --delete-resources  enables deletion of resources if they are missing in the definition
-
-  --local                 work in local mode, not updating the referenced default config
-
-  -v, --verbose           enable verbose output (-vvv for more verbose output)
   -h, --help              Show this message and exit.
 ```
 
@@ -39,7 +40,7 @@ When the `apply` operation is executed, the following happens:
 ## Example
 
 ```shell
-tn@proteus:~/.../otterdog-configs$ otterdog apply adoptium
+$ otterdog apply adoptium
 
 Apply changes for configuration at '.../otterdog-configs/otterdog.json'
 
@@ -53,21 +54,21 @@ Organization adoptium[id=adoptium]
   there have been 4 validation infos, enable verbose output with '-v' to to display them.
 
   ~ settings {
-    ~ name                                                     = "Eclipse Adoptium" -> "Eclipse Adoptium Project"
+    ~ name                        = "Eclipse Adoptium" -> "Eclipse Adoptium Project"
     }
 
   - remove repository[name="Incubator"] {
-    - allow_auto_merge                                         = False
-    - allow_forking                                            = True
-    - allow_merge_commit                                       = True
-    - name                                                     = "Incubator"
+    - allow_auto_merge            = False
+    - allow_forking               = True
+    - allow_merge_commit          = True
+    - name                        = "Incubator"
     ...
   - }
 
   + add repository[name="Incubator-New"] {
-    + allow_auto_merge                                         = False
-    + allow_forking                                            = True
-    + name                                                     = "Incubator-New"
+    + allow_auto_merge            = False
+    + allow_forking               = True
+    + name                        = "Incubator-New"
     ...
   + }
 

diff --git a/docs/reference/operations/import.md b/docs/reference/operations/import.md
@@ -22,7 +22,7 @@ them locally in a file `<github-id>/<github-id>.jsonnet` in the organization spe
 ## Example
 
 ```shell
-tn@proteus:~/workspace/eclipse/EclipseFdn/otterdog-configs$ otterdog import adoptium -f
+$ otterdog import adoptium -f
 
 Importing resources for configuration at '.../otterdog-configs/otterdog.json'
 

diff --git a/docs/reference/operations/validate.md b/docs/reference/operations/validate.md
@@ -0,0 +1,33 @@
+The `validate` operation will validate the local configuration on syntax and semantic level and provide feedback:
+
+- Info: minor remarks, configuration can be applied, only visible when running with `-v`
+- Warning: non-critical but configuration will not be applied as specified
+- Error: critical, configuration can not be applied and need to be adapted
+
+## Options
+
+```shell
+  --local            work in local mode, not updating the referenced default config
+  -c, --config FILE  configuration file to use  [default: otterdog.json]
+  -v, --verbose      enable verbose output (-vvv for more verbose output)
+  -h, --help         Show this message and exit.
+```
+
+## Example
+
+```shell
+$ otterdog validate eclipse-csi -v
+
+Validating organization configurations:
+
+Organization technology.csi[id=eclipse-csi] (1/1)
+╷
+│ Info: org_secret[name="DEPENDENCY_TRACK_API_KEY"] will be skipped during processing:
+│
+│    only a dummy value '********' is provided in the configuration.
+╵
+╷
+│ Error: repository[name="octopin"] has defined an invalid topic 'github actions'. Only lower-case, numbers and '-' are allowed characters.
+╵
+  Validation failed: 1 info(s), 0 warning(s), 1 error(s)
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -70,9 +70,9 @@ nav:
              - Status Check: reference/organization/repository/status-check.md
     - CLI Operations:
         - reference/operations/index.md
+        - Apply: reference/operations/apply.md
         - Import: reference/operations/import.md
         - Plan: reference/operations/plan.md
-        - Apply: reference/operations/apply.md
         - Validate: reference/operations/validate.md
 - User Guide:
     - Renaming of Resources: userguide/renaming.md