Doc(eos_designs): Improve documentation (aristanetworks#2962)

Co-authored-by: Claus Holbech <[email protected]>

.github/.markdownlintignore

@@ -1,4 +1,4 @@
 ansible_collections/arista/avd/molecule/
 ansible_collections/arista/avd/examples/*/documentation/
 ansible_collections/arista/avd/tests/unit/filters/toc_files/
-ansible_collections/arista/avd/roles/eos_designs/docs/
+ansible_collections/arista/avd/roles/eos_designs/schemas/doc_fragments/

.pre-commit-config.yaml

@@ -72,7 +72,7 @@ repos:
     hooks:
       - id: schemas
         name: Build AVD Schemas and Documentation
-        entry: sh -c 'exec env ANSIBLE_COLLECTIONS_PATHS=`pwd` ansible-playbook arista.avd._build_schemas_and_docs'
+        entry: sh -c 'exec env ANSIBLE_COLLECTIONS_PATHS=`pwd` ansible-playbook --forks 10 arista.avd._build_schemas_and_docs'
         language: system
         files: ansible_collections/arista/avd/roles/[a-z_]+/schemas
         pass_filenames: false

ansible_collections/arista/avd/docs/contribution/eos_designs_internal_notes.md

@@ -142,7 +142,7 @@ TODO
 The class is instantiated once per device. Methods may use references to other device instances using `hostvars.avd_switch_facts`,
 which is a dict of `EosDesignsfacts` instances covering all devices.
 
-See the source code [here](../../plugins/plugin_utils/eos_designs_facts/)
+See the source code [here](../../plugins/plugin_utils/eos_designs_facts/__init__.py)
 
 ```mermaid
 classDiagram
@@ -173,7 +173,7 @@ classDiagram
 
 ### SharedUtils
 
-See the source code [here](../../plugins/plugin_utils/eos_designs_shared_utils/)
+See the source code [here](../../plugins/plugin_utils/eos_designs_shared_utils/__init__.py)
 
 ```mermaid
 classDiagram
@@ -226,17 +226,17 @@ Subclasses are typically using Mixin classes to split all the attributes/`cached
 
 Source code:
 
-- [AvdStructuredConfigBase](../../roles/eos_designs/python_modules/base/)
+- [AvdStructuredConfigBase](../../roles/eos_designs/python_modules/base/__init__.py)
   (Unfortunate naming. Base here refers to base configurations. Not a Base class.)
-- [AvdStructuredConfigConnectedEndpoints](../../roles/eos_designs/python_modules/connected_endpoints/)
-- [AvdStructuredConfigCoreInterfaces](../../roles/eos_designs/python_modules/core_interfaces/)
-- [AvdStructuredConfigCustomStructuredConfiguration](../../roles/eos_designs/python_modules/custom_structured_configuration/)
-- [AvdStructuredConfigInbandManagement](../../roles/eos_designs/python_modules/inband_management/)
-- [AvdStructuredConfigL3Edge](../../roles/eos_designs/python_modules/l3_edge/)
-- [AvdStructuredConfigMlag](../../roles/eos_designs/python_modules/mlag/)
-- [AvdStructuredConfigNetworkServices](../../roles/eos_designs/python_modules/network_services/)
-- [AvdStructuredConfigOverlay](../../roles/eos_designs/python_modules/overlay/)
-- [AvdStructuredConfigUnderlay](../../roles/eos_designs/python_modules/underlay/)
+- [AvdStructuredConfigConnectedEndpoints](../../roles/eos_designs/python_modules/connected_endpoints/__init__.py)
+- [AvdStructuredConfigCoreInterfaces](../../roles/eos_designs/python_modules/core_interfaces/__init__.py)
+- [AvdStructuredConfigCustomStructuredConfiguration](../../roles/eos_designs/python_modules/custom_structured_configuration/__init__.py)
+- [AvdStructuredConfigInbandManagement](../../roles/eos_designs/python_modules/inband_management/__init__.py)
+- [AvdStructuredConfigL3Edge](../../roles/eos_designs/python_modules/l3_edge/__init__.py)
+- [AvdStructuredConfigMlag](../../roles/eos_designs/python_modules/mlag/__init__.py)
+- [AvdStructuredConfigNetworkServices](../../roles/eos_designs/python_modules/network_services/__init__.py)
+- [AvdStructuredConfigOverlay](../../roles/eos_designs/python_modules/overlay/__init__.py)
+- [AvdStructuredConfigUnderlay](../../roles/eos_designs/python_modules/underlay/__init__.py)
 
 ```mermaid
 classDiagram

ansible_collections/arista/avd/docs/input-variable-validation.md → ansible_collections/arista/avd/docs/contribution/input-variable-validation.md

@@ -1,7 +1,6 @@
 # Validation of Input Variables
 
 !!! NOTE
-    - Schemas for all input data models are still under development
     - Some schema validations are not implemented yet.
 
 `eos_designs` and `eos_cli_config_gen` support a wide range of input variables described under the role documentation sections.
@@ -120,15 +119,15 @@ This fragment will be merged with other fragments during development, to form th
 
 For reference, the full Role Schemas can be found here:
 
-- [`eos_designs` AVD Schema, not ready yet](../roles/eos_designs/schemas/eos_designs.schema.yml)
-- [`eos_cli_config_gen` AVD Schema](../roles/eos_cli_config_gen/schemas/eos_cli_config_gen.schema.yml)
+- [`eos_designs` AVD Schema, not ready yet](../../roles/eos_designs/schemas/eos_designs.schema.yml)
+- [`eos_cli_config_gen` AVD Schema](../../roles/eos_cli_config_gen/schemas/eos_cli_config_gen.schema.yml)
 
 The supported schema options depend on the type of variable that is described. The supported types are `int`, `bool`, `str`,
 `dict` and `list`. The schema does not support mixed types for the same variable, but the automatic type conversion mentioned
 above can address the usability aspect by helping the user with common mistakes.
 
 The supported schema options for AVD Schema are described in a meta-schema using JSON Schema Draft-7 format. The meta-schema
-can be seen [here](../plugins/plugin_utils/schema/avd_meta_schema.json). In addition, below is a more detailed description of the supported
+can be seen [here](../../plugins/plugin_utils/schema/avd_meta_schema.json). In addition, below is a more detailed description of the supported
 schema options per variable type.
 
 All schema options (ex. `type`, `max`, `valid_values`) are validated individually, and to pass the validation, the data must
@@ -159,8 +158,6 @@ This also means that a poorly written schema could have conflicting schema optio
 | <samp>&nbsp;&nbsp;remove_after_date</samp> | String | | | | Date after which the key will be removed |
 | <samp>$ref</samp> | String | | | | Reference to Sub Schema using JSON Schema resolver<br>Example '#/keys/mykey' will resolve the schema for 'mykey' under the root dictionary of the current schema |
 | <samp>documentation_options</samp> | Dictionary | | | | Special options used for generating documentation |
-| <samp>&nbsp;&nbsp;filename</samp> | String | | "Input Variables" | | Setting 'filename' will allow for custom grouping of schema sections in the documentation.<br>By default all sections will be part of the same 'Input Variables.md' file. By setting 'filename' the sections and tables for one or more keys can be moved to separate file.<br>The 'filename' option is inherited to all child keys, unless specifically set on the child. |
-| <samp>&nbsp;&nbsp;section</samp> | String | | | | Setting 'section' will allow for custom grouping of schema tables in the documentation.<br>By default all tables will be part of the same 'Input Variables' section. By setting 'section' the tables for one or more keys can be moved to separate section.<br>The 'section' option is inherited to all child keys, unless specifically set on the child. |
 | <samp>&nbsp;&nbsp;table</samp> | String | | | | Setting 'table' will allow for custom grouping of schema fields in the documentation.<br>By default each root key has it's own table. By setting the same table-value on multiple keys, they will be merged to a single table.<br>If 'table' is set on a 'child' key, all "ancestor" keys are automatically included in the table so the full path is visible.<br>The 'table' option is inherited to all child keys, unless specifically set on the child. |
 
 The meta-schema does not allow for other keys to be set in the schema.
@@ -186,8 +183,6 @@ The meta-schema does not allow for other keys to be set in the schema.
 | <samp>&nbsp;&nbsp;remove_after_date</samp> | String | | | | Date after which the key will be removed |
 | <samp>$ref</samp> | String | | | | Reference to Sub Schema using JSON Schema resolver<br>Example '#/keys/mykey' will resolve the schema for 'mykey' under the root dictionary of the current schema |
 | <samp>documentation_options</samp> | Dictionary | | | | Special options used for generating documentation |
-| <samp>&nbsp;&nbsp;filename</samp> | String | | "Input Variables" | | Setting 'filename' will allow for custom grouping of schema sections in the documentation.<br>By default all sections will be part of the same 'Input Variables.md' file. By setting 'filename' the sections and tables for one or more keys can be moved to separate file.<br>The 'filename' option is inherited to all child keys, unless specifically set on the child. |
-| <samp>&nbsp;&nbsp;section</samp> | String | | | | Setting 'section' will allow for custom grouping of schema tables in the documentation.<br>By default all tables will be part of the same 'Input Variables' section. By setting 'section' the tables for one or more keys can be moved to separate section.<br>The 'section' option is inherited to all child keys, unless specifically set on the child. |
 | <samp>&nbsp;&nbsp;table</samp> | String | | | | Setting 'table' will allow for custom grouping of schema fields in the documentation.<br>By default each root key has it's own table. By setting the same table-value on multiple keys, they will be merged to a single table.<br>If 'table' is set on a 'child' key, all "ancestor" keys are automatically included in the table so the full path is visible.<br>The 'table' option is inherited to all child keys, unless specifically set on the child. |
 
 The meta-schema does not allow for other keys to be set in the schema.
@@ -218,8 +213,6 @@ The meta-schema does not allow for other keys to be set in the schema.
 | <samp>&nbsp;&nbsp;remove_after_date</samp> | String | | | | Date after which the key will be removed |
 | <samp>$ref</samp> | String | | | | Reference to Sub Schema using JSON Schema resolver<br>Example '#/keys/mykey' will resolve the schema for 'mykey' under the root dictionary of the current schema |
 | <samp>documentation_options</samp> | Dictionary | | | | Special options used for generating documentation |
-| <samp>&nbsp;&nbsp;filename</samp> | String | | "Input Variables" | | Setting 'filename' will allow for custom grouping of schema sections in the documentation.<br>By default all sections will be part of the same 'Input Variables.md' file. By setting 'filename' the sections and tables for one or more keys can be moved to separate file.<br>The 'filename' option is inherited to all child keys, unless specifically set on the child. |
-| <samp>&nbsp;&nbsp;section</samp> | String | | | | Setting 'section' will allow for custom grouping of schema tables in the documentation.<br>By default all tables will be part of the same 'Input Variables' section. By setting 'section' the tables for one or more keys can be moved to separate section.<br>The 'section' option is inherited to all child keys, unless specifically set on the child. |
 | <samp>&nbsp;&nbsp;table</samp> | String | | | | Setting 'table' will allow for custom grouping of schema fields in the documentation.<br>By default each root key has it's own table. By setting the same table-value on multiple keys, they will be merged to a single table.<br>If 'table' is set on a 'child' key, all "ancestor" keys are automatically included in the table so the full path is visible.<br>The 'table' option is inherited to all child keys, unless specifically set on the child. |
 
 The meta-schema does not allow for other keys to be set in the schema.
@@ -246,8 +239,6 @@ The meta-schema does not allow for other keys to be set in the schema.
 | <samp>&nbsp;&nbsp;remove_after_date</samp> | String | | | | Date after which the key will be removed |
 | <samp>$ref</samp> | String | | | | Reference to Sub Schema using JSON Schema resolver<br>Example '#/keys/mykey' will resolve the schema for 'mykey' under the root dictionary of the current schema |
 | <samp>documentation_options</samp> | Dictionary | | | | Special options used for generating documentation |
-| <samp>&nbsp;&nbsp;filename</samp> | String | | "Input Variables" | | Setting 'filename' will allow for custom grouping of schema sections in the documentation.<br>By default all sections will be part of the same 'Input Variables.md' file. By setting 'filename' the sections and tables for one or more keys can be moved to separate file.<br>The 'filename' option is inherited to all child keys, unless specifically set on the child. |
-| <samp>&nbsp;&nbsp;section</samp> | String | | | | Setting 'section' will allow for custom grouping of schema tables in the documentation.<br>By default all tables will be part of the same 'Input Variables' section. By setting 'section' the tables for one or more keys can be moved to separate section.<br>The 'section' option is inherited to all child keys, unless specifically set on the child. |
 | <samp>&nbsp;&nbsp;table</samp> | String | | | | Setting 'table' will allow for custom grouping of schema fields in the documentation.<br>By default each root key has it's own table. By setting the same table-value on multiple keys, they will be merged to a single table.<br>If 'table' is set on a 'child' key, all "ancestor" keys are automatically included in the table so the full path is visible.<br>The 'table' option is inherited to all child keys, unless specifically set on the child. |
 
 The meta-schema does not allow for other keys to be set in the schema.
@@ -271,8 +262,6 @@ The meta-schema does not allow for other keys to be set in the schema.
 | <samp>&nbsp;&nbsp;remove_after_date</samp> | String | | | | Date after which the key will be removed |
 | <samp>$ref</samp> | String | | | | Reference to Sub Schema using JSON Schema resolver<br>Allows for easy reuse of schema definitions.<br>Example '#/keys/mykey' will resolve the schema for 'mykey' under the root dictionary of the current schema |
 | <samp>documentation_options</samp> | Dictionary | | | | Special options used for generating documentation |
-| <samp>&nbsp;&nbsp;filename</samp> | String | | "Input Variables" | | Setting 'filename' will allow for custom grouping of schema sections in the documentation.<br>By default all sections will be part of the same 'Input Variables.md' file. By setting 'filename' the sections and tables for one or more keys can be moved to separate file.<br>The 'filename' option is inherited to all child keys, unless specifically set on the child. |
-| <samp>&nbsp;&nbsp;section</samp> | String | | | | Setting 'section' will allow for custom grouping of schema tables in the documentation.<br>By default all tables will be part of the same 'Input Variables' section. By setting 'section' the tables for one or more keys can be moved to separate section.<br>The 'section' option is inherited to all child keys, unless specifically set on the child. |
 | <samp>&nbsp;&nbsp;table</samp> | String | | | | Setting 'table' will allow for custom grouping of schema fields in the documentation.<br>By default each root key has it's own table. By setting the same table-value on multiple keys, they will be merged to a single table.<br>If 'table' is set on a 'child' key, all "ancestor" keys are automatically included in the table so the full path is visible.<br>The 'table' option is inherited to all child keys, unless specifically set on the child. |
 
 The meta-schema does not allow for other keys to be set in the schema.