auto-generation of config documentations.

zio · May 22, 2024 · c9af2a9 · c9af2a9
1 parent 8275264
commit c9af2a9
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 73 deletions.
diff --git a/docs/auto-generation-of-config-documentation.md b/docs/auto-generation-of-config-documentation.md
@@ -0,0 +1,81 @@
+---
+id: auto-generation-of-config-documentation
+title: "Auto-generation of Config Documentation"
+---
+
+ZIO Config has a built-in support for generating documentation for the configuration descriptors. This feature is useful for library authors to provide documentation for their configuration stuff. No matter how we have defined our config descriptors, manually or automatically using magnolia, we can generate documentation for them.
+
+## Example 1: Simple Configuration
+
+```scala mdoc:silent
+import utils._
+
+printSource("examples/shared/src/main/scala/zio/config/examples/documentation/GeneratingConfigDocumentation.scala")
+```
+
+Here is the output:
+
+```md
+auto-generated documentation of MyConfig:
+
+## Configuration Details
+
+
+|FieldName|Format                     |Description|Sources|
+|---      |---                        |---        |---    |
+|         |[all-of](fielddescriptions)|           |       |
+
+### Field Descriptions
+
+|FieldName|Format   |Description                       |Sources|
+|---      |---      |---                               |---    |
+|LDAP     |primitive|a text property, Related to auth  |       |
+|PORT     |primitive|an integer property, Database port|       | 
+|DB_URL   |primitive|a text property, URL of database  |       |
+```
+
+Currently, ZIO Config supports generating the documentation in two flavors: GitHub and Confluence markdown.
+
+## Example 2: Nested Configuration
+
+Here is another example, which includes nested configuration values:
+
+```scala mdoc:silent
+import utils._
+printSource("examples/shared/src/main/scala/zio/config/examples/documentation/NestedConfigDocumentation.scala")
+```
+
+Let's see how the documentation looks like:
+
+```md
+Auto-generated documentation of AppConfig:
+
+## Configuration Details
+
+
+|FieldName|Format                     |Description|Sources|
+|---      |---                        |---        |---    |
+|         |[all-of](fielddescriptions)|           |       |
+
+### Field Descriptions
+
+|FieldName                 |Format               |Description                        |Sources|
+|---                       |---                  |---                                |---    |
+|SECRET                    |primitive            |a text property, Application secret|       |
+|[CREDENTIALS](credentials)|[all-of](credentials)|Credentials                        |       |
+|[DATABASE](database)      |[all-of](database)   |Database                           |       |
+
+### CREDENTIALS
+
+|FieldName|Format   |Description                      |Sources|
+|---      |---      |---                              |---    |
+|USERNAME |primitive|a text property, Example: ZioUser|       |
+|PASSWORD |primitive|a text property, Example: ZioPass|       |
+
+### DATABASE
+
+|FieldName|Format   |Description                       |Sources|
+|---      |---      |---                               |---    |
+|PORT     |primitive|an integer property, Example: 8088|       |
+|URL      |primitive|a text property, Example: abc.com |       |
+```
diff --git a/docs/dive-into-zio-config.md b/docs/dive-into-zio-config.md
@@ -74,79 +74,6 @@ val source = ConfigProvider.fromMap(map)
 source.load(MyConfig.config)
 ```
 
-## Generating Config Documentation
-
-```scala mdoc:silent
-import utils._
-
-printSource("examples/shared/src/main/scala/zio/config/examples/documentation/GeneratingConfigDocumentation.scala")
-```
-
-Here is the output:
-
-```md
-auto-generated documentation of MyConfig:
-
-## Configuration Details
-
-
-|FieldName|Format                     |Description|Sources|
-|---      |---                        |---        |---    |
-|         |[all-of](fielddescriptions)|           |       |
-
-### Field Descriptions
-
-|FieldName|Format   |Description                       |Sources|
-|---      |---      |---                               |---    |
-|LDAP     |primitive|a text property, Related to auth  |       |
-|PORT     |primitive|an integer property, Database port|       | 
-|DB_URL   |primitive|a text property, URL of database  |       |
-```
-
-Currently, ZIO Config supports generating the documentation in two flavors: GitHub and Confluence markdown.
-
-Here is another example, which includes nested configuration values:
-
-```scala mdoc:silent
-import utils._
-printSource("examples/shared/src/main/scala/zio/config/examples/documentation/NestedConfigDocumentation.scala")
-```
-
-Let's see how the documentation looks like:
-
-```md
-Auto-generated documentation of AppConfig:
-
-## Configuration Details
-
-
-|FieldName|Format                     |Description|Sources|
-|---      |---                        |---        |---    |
-|         |[all-of](fielddescriptions)|           |       |
-
-### Field Descriptions
-
-|FieldName                 |Format               |Description                        |Sources|
-|---                       |---                  |---                                |---    |
-|SECRET                    |primitive            |a text property, Application secret|       |
-|[CREDENTIALS](credentials)|[all-of](credentials)|Credentials                        |       |
-|[DATABASE](database)      |[all-of](database)   |Database                           |       |
-
-### CREDENTIALS
-
-|FieldName|Format   |Description                      |Sources|
-|---      |---      |---                              |---    |
-|USERNAME |primitive|a text property, Example: ZioUser|       |
-|PASSWORD |primitive|a text property, Example: ZioPass|       |
-
-### DATABASE
-
-|FieldName|Format   |Description                       |Sources|
-|---      |---      |---                               |---    |
-|PORT     |primitive|an integer property, Example: 8088|       |
-|URL      |primitive|a text property, Example: abc.com |       |
-```
-
 ## Accumulating all errors
 
 For any misconfiguration, the `ReadError` collects all of them with proper semantics: `AndErrors` and `OrErrors`.

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -8,6 +8,7 @@ const sidebars = {
       items: [
         "index",
         "dive-into-zio-config",
+        "auto-generation-of-config-documentation",
         "integrations",
         "automatic-derivation-of-config",
         "read-from-various-sources",