Doc: Migrating documentation to MD and within modules (#678)

* updating build file, links, outputs * Output updates, how-to removal, mkdocs TOC * Corrected links * pre-commit and more link fixes * updated build script to handle ansible-test errors, removed invalid keys from module. * Non required shebang * updates to link checking * corrected down command in compose * add change control v3 output * add remove output in change control * Minor grammar and version table edits * merging changes from pr/589 * update to python3 * address feadback from review * fixed configlet example --------- Co-authored-by: Sugetha Chandhrasekar <[email protected]> Co-authored-by: Carl Buchmann <[email protected]>
aristanetworks · Nov 20, 2023 · 2258ca5 · 2258ca5
1 parent f8007d9
commit 2258ca5
Show file tree

Hide file tree

Showing 94 changed files with 2,071 additions and 6,623 deletions.
diff --git a/.github/workflows/pull-request-management.yml b/.github/workflows/pull-request-management.yml
@@ -215,18 +215,16 @@ jobs:
     runs-on: ubuntu-latest
     needs: [file-changes]
     if: needs.file-changes.outputs.docs == 'true'
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v3
       - name: 'start docker-compose stack'
         run: |
-          cp development/docker-compose.yml .
-          sed -i 's/cd\sansible-cvp\/\s\&\&//g' docker-compose.yml
-          docker-compose -f docker-compose.yml up -d webdoc_cvp
-          docker-compose -f docker-compose.yml ps
+          docker-compose -f development/docker-compose.yml up -d webdoc_cvp
+          docker-compose -f development/docker-compose.yml ps
       - name: 'test connectivity to mkdoc server'
         run: |
-          sleep 30
-          until docker exec webdoc_cvp curl -s -I http://localhost:8000/ ; do sleep 2; done
+          bash -c 'while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' 127.0.0.1:8000)" != "200" ]]; do sleep 5; done'
       - name: check links for 404
         run: |
           docker run --network container:webdoc_cvp raviqqe/muffet:2.6.1 http://127.0.0.1:8000 \
@@ -242,7 +240,7 @@ jobs:
             --timeout=30
       - name: 'stop docker-compose stack'
         run: |
-          docker-compose -f docker-compose.yml down
+          docker-compose -f development/docker-compose.yml down
 
   ansible_test:
     name: Run ansible-test validation

diff --git a/Makefile b/Makefile
@@ -11,7 +11,7 @@ ANSIBLE_TEST_MODE ?= docker
 # Python version to use in testing.
 ANSIBLE_TEST_PYTHON ?= 3.6
 # Root path for MKDOCS content
-WEBDOC_BUILD = ansible_collections/arista/cvp/docs/_build
+WEBDOC_BUILD = ansible_collections/arista/cvp/docs/build-md
 COMPOSE_FILE ?= development/docker-compose.yml
 MUFFET_TIMEOUT ?= 60
 
@@ -91,8 +91,7 @@ build-docker3: ## [DEPRECATED] visit https://github.com/arista-netdevops-communi
 .PHONY: webdoc
 webdoc: ## Build documentation to publish static content
 	( cd $(WEBDOC_BUILD) ; \
-	python ansible2rst.py ; \
-	find . -name 'cv_*_v3.rst' -exec pandoc {} --from rst --to gfm -o ../modules/{}.md \;)
+	python3 doc.py)
 	cp $(CURRENT_DIR)/contributing.md $(WEBDOC_BUILD)/.. ;\
 
 .PHONY: check-cvp-404

diff --git a/README.md b/README.md
@@ -31,12 +31,12 @@ This repository provides content for Ansible's collection **arista.cvp** with fo
 
 **Version 3:**
 
-- [**arista.cvp.cv_configlet_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_configlet_v3.rst/) -  Manage configlet configured on CVP.
-- [**arista.cvp.cv_container_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_container_v3.rst/) -  Manage container topology and attach configlet and devices to containers.
-- [**arista.cvp.cv_device_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_device_v3.rst/) - Manage devices configured on CVP
-- [**arista.cvp.cv_task_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_task_v3.rst/) - Run tasks created on CVP.
-- [**arista.cvp.cv_facts_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_facts_v3.rst/) - Collect information from CloudVision.
-- [**arista.cvp.cv_image_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_image_v3.rst/) - Create EOS images and bundles on CloudVision.
+- [**arista.cvp.cv_configlet_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_configlet_v3.md) -  Manage configlet configured on CVP.
+- [**arista.cvp.cv_container_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_container_v3.md) -  Manage container topology and attach configlet and devices to containers.
+- [**arista.cvp.cv_device_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_device_v3.md) - Manage devices configured on CVP
+- [**arista.cvp.cv_task_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_task_v3.md) - Run tasks created on CVP.
+- [**arista.cvp.cv_facts_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_facts_v3.md) - Collect information from CloudVision.
+- [**arista.cvp.cv_image_v3**](https://cvp.avd.sh/en/latest/docs/modules/cv_image_v3.md) - Create EOS images and bundles on CloudVision.
 
 ### List of available roles
 
@@ -45,11 +45,11 @@ This repository provides content for Ansible's collection **arista.cvp** with fo
 
 ## Deprecated modules
 
-- [**arista.cvp.cv_facts**](https://cvp.avd.sh/en/latest/docs/modules/cv_facts.rst/) - Collect CVP facts from server like list of containers, devices, configlet and tasks.
-- [**arista.cvp.cv_configlet**](https://cvp.avd.sh/en/latest/docs/modules/cv_configlet.rst/) -  Manage configlet configured on CVP.
-- [**arista.cvp.cv_container**](https://cvp.avd.sh/en/latest/docs/modules/cv_container.rst/) -  Manage container topology and attach configlet and devices to containers.
-- [**arista.cvp.cv_device**](https://cvp.avd.sh/en/latest/docs/modules/cv_device.rst/) - Manage devices configured on CVP
-- [**arista.cvp.cv_task**](https://cvp.avd.sh/en/latest/docs/modules/cv_task.rst/) - Run tasks created on CVP.
+- [**arista.cvp.cv_facts**](https://cvp.avd.sh/en/latest/docs/modules/cv_facts.md) - Collect CVP facts from server like list of containers, devices, configlet and tasks.
+- [**arista.cvp.cv_configlet**](https://cvp.avd.sh/en/latest/docs/modules/cv_configlet.md) -  Manage configlet configured on CVP.
+- [**arista.cvp.cv_container**](https://cvp.avd.sh/en/latest/docs/modules/cv_container.md) -  Manage container topology and attach configlet and devices to containers.
+- [**arista.cvp.cv_device**](https://cvp.avd.sh/en/latest/docs/modules/cv_device.md) - Manage devices configured on CVP
+- [**arista.cvp.cv_task**](https://cvp.avd.sh/en/latest/docs/modules/cv_task.md) - Run tasks created on CVP.
 
 ## Example
 

diff --git a/ansible_collections/arista/cvp/README.md b/ansible_collections/arista/cvp/README.md
@@ -2,37 +2,38 @@
 
 ## About
 
-[Arista Networks](https://www.arista.com/) supports Ansible for managing devices running the EOS operating system through [CloudVision platform (CVP)](https://www.arista.com/en/products/eos/eos-cloudvision). This collection includes a set of ansible modules that perform specific configuration tasks on CVP server. These tasks include: collecting facts, managing configlets, building topology with containers and devices, running tasks.
+[Arista Networks](https://www.arista.com/) supports Ansible for managing devices running the EOS operating system through [CloudVision platform (CVP)](https://www.arista.com/en/products/eos/eos-cloudvision). This collection includes a set of Ansible modules that perform specific configuration tasks on a CVP server. These tasks include collecting facts, managing configlets, building topology with containers and devices, and running tasks.
 
 <p align="center">
   <img src='medias/ansible-cloudvision.png' alt='Arista CloudVision and Ansible'/>
 </p>
 
-Even if **`arista.cvp`** collection is integrated with `arista.avd` collection to [automate configuration deployment](https://avd.sh/en/latest/roles/eos_config_deploy_cvp/index.html), this collection can also be used outside of AVD tasks to populate your CloudVision server with your own workflows.
+Even if **`arista.cvp`** collection is integrated with `arista.avd` collection to [automate configuration deployment](https://avd.sh/en/latest/roles/eos_config_deploy_cvp/index.html), this collection can also be used outside of AVD tasks to populate your CloudVision server with your workflows.
 
 ## Requirements
 
 ### Arista CloudVision
 
 Current active branch:
 
-- **CVP 2020.2.x and onward**: starting version [`ansible-cvp 2.0.0`](https://github.com/aristanetworks/ansible-cvp/releases/tag/v2.0.0)
+- **CVP 2021.3.x and onward**: starting with `ansible-cvp 3.9.0`
 
 !!! info
-    Starting version 2.0.0, collection uses [cvprac](https://github.com/aristanetworks/cvprac) as CloudVision connection manager. So support for any new CLoudvision server is tied to it support in this python library.
+    Starting with version 2.0.0, the collection uses [cvprac](https://github.com/aristanetworks/cvprac) as the CloudVision connection manager. So support for any new CloudVision server is tied to it's support in the cvprac Python library.
 
-| ansible-cvp | 1.0.0 | 1.1.0 | >= 2.0.0 |
-| ----------- | ----- | ----- | -------- |
-| 2018.2 | ✅ | ✅ | ✅ |
-| 2019.x | ✅ | ✅ | ✅ |
-| 2020.1 | | ✅ | ✅ |
-| >= 2020.2 | | | ✅ |
+| ansible-cvp | 1.0.0 | 1.1.0 | >= 2.0.0 |>= 3.9.0 |
+| ----------- | ----- | ----- | -------- | -------- |
+| 2018.2 | ✅ | ✅ | ✅ | |
+| 2019.x | ✅ | ✅ | ✅ | |
+| 2020.1 | | ✅ | ✅ | |
+| >= 2020.2 | | | ✅ | |
+| >= 2021.3 | | | | ✅ |
 
 ### Python
 
 - Python `>=3.8`
 
-Please check the minimum version supported by your ansible installation on [ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#control-node-requirements)
+Please check the minimum version supported by your ansible installation on the [ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#control-node-requirements).
 
 ### Additional Python Libraries required
 
@@ -79,15 +80,15 @@ This repository provides content for Ansible's collection **arista.cvp** with fo
 
 **Version 3:**
 
-- [**arista.cvp.cv_configlet_v3**](docs/modules/cv_configlet_v3.rst/) -  Manage configlet configured on CVP.
-- [**arista.cvp.cv_container_v3**](docs/modules/cv_container_v3.rst/) -  Manage container topology and attach configlet and devices to containers.
-- [**arista.cvp.cv_device_v3**](docs/modules/cv_device_v3.rst/) - Manage devices configured on CVP
-- [**arista.cvp.cv_task_v3**](docs/modules/cv_task_v3.rst/) - Run tasks created on CVP.
-- [**arista.cvp.cv_facts_v3**](docs/modules/cv_facts_v3.rst/) - Collect information from CloudVision.
-- [**arista.cvp.cv_image_v3**](docs/modules/cv_image_v3.rst/) - Create EOS images and bundles on CloudVision.
-- [**arista.cvp.cv_tag_v3**](docs/modules/cv_tag_v3.rst/) - Create, delete, assign and unassign tags on CloudVision.
-- [**arista.cvp.cv_validate_v3**](docs/modules/cv_validate_v3.rst/) - Configlet validation
-- [**arista.cvp.cv_change_control_v3**](docs/modules/cv_change_control_v3.rst/) - Manage change controls on CloudVision.
+- [**arista.cvp.cv_configlet_v3**](docs/modules/cv_configlet_v3.md) -  Manage configlet configured on CVP.
+- [**arista.cvp.cv_container_v3**](docs/modules/cv_container_v3.md) -  Manage container topology and attach configlet and devices to containers.
+- [**arista.cvp.cv_device_v3**](docs/modules/cv_device_v3.md) - Manage devices configured on CVP
+- [**arista.cvp.cv_task_v3**](docs/modules/cv_task_v3.md) - Run tasks created on CVP.
+- [**arista.cvp.cv_facts_v3**](docs/modules/cv_facts_v3.md) - Collect information from CloudVision.
+- [**arista.cvp.cv_image_v3**](docs/modules/cv_image_v3.md) - Create EOS images and bundles on CloudVision.
+- [**arista.cvp.cv_tag_v3**](docs/modules/cv_tag_v3.md) - Create, delete, assign and unassign tags on CloudVision.
+- [**arista.cvp.cv_validate_v3**](docs/modules/cv_validate_v3.md) - Configlet validation
+- [**arista.cvp.cv_change_control_v3**](docs/modules/cv_change_control_v3.md) - Manage change controls on CloudVision.
 
 ### List of available roles
 
@@ -96,21 +97,21 @@ This repository provides content for Ansible's collection **arista.cvp** with fo
 
 ### Deprecated modules
 
-- [**arista.cvp.cv_facts**](docs/modules/cv_facts.rst/) - Collect CVP facts from server like list of containers, devices, configlet and tasks.
-- [**arista.cvp.cv_configlet**](docs/modules/cv_configlet.rst/) -  Manage configlet configured on CVP.
-- [**arista.cvp.cv_container**](docs/modules/cv_container.rst/) -  Manage container topology and attach configlet and devices to containers.
-- [**arista.cvp.cv_device**](docs/modules/cv_device.rst/) - Manage devices configured on CVP
-- [**arista.cvp.cv_task**](docs/modules/cv_task.rst/) - Run tasks created on CVP.
+- [**arista.cvp.cv_facts**](docs/modules/cv_facts.md) - Collect CVP facts from server like list of containers, devices, configlet and tasks.
+- [**arista.cvp.cv_configlet**](docs/modules/cv_configlet.md) -  Manage configlet configured on CVP.
+- [**arista.cvp.cv_container**](docs/modules/cv_container.md) -  Manage container topology and attach configlet and devices to containers.
+- [**arista.cvp.cv_device**](docs/modules/cv_device.md) - Manage devices configured on CVP
+- [**arista.cvp.cv_task**](docs/modules/cv_task.md) - Run tasks created on CVP.
 
 ## Example
 
-This example outlines how to use `arista.cvp` to create a containers topology on Arista CloudVision.
+This example outlines how to use `arista.cvp` to create a container's topology on Arista CloudVision.
 
-A dedicated repository is available for step by step examples on [ansible-cvp-toi](https://github.com/arista-netdevops-community/ansible-cvp-toi).
+A dedicated repository is available for step-by-step examples on [ansible-cvp-toi](https://github.com/arista-netdevops-community/ansible-cvp-toi).
 
-A [complete end to end demo](https://github.com/arista-netdevops-community/ansible-avd-cloudvision-demo) using [Arista Validated Design collection](https://github.com/aristanetworks/ansible-avd) and CloudVision modules is available as an example.
+A [complete end-to-end demo](https://github.com/arista-netdevops-community/ansible-avd-cloudvision-demo) using [Arista Validated Design collection](https://github.com/aristanetworks/ansible-avd) and CloudVision modules is available as an example.
 
-Below is a very basic example to build a container topology on a CloudVision platform assuming you have 3 veos named `veos0{1,3}` and a configlet named `alias`
+Below is a very basic example of build a container topology on a CloudVision platform, assuming you have three vEOS named `veos0{1,3}` and a configlet named `alias`.
 
 ```yaml
 ---
@@ -182,15 +183,15 @@ As modules of this collection are based on [`HTTPAPI` connection plugin](https:/
 
 ## License
 
-Project is published under [Apache License](LICENSE).
+The project is published under [Apache License](LICENSE).
 
 ## Ask a question
 
 To report a bug, discuss or request a specific feature, please open a [GitHub issue](https://github.com/aristanetworks/ansible-cvp/issues) using the appropriate template.
 
 ## Contributing
 
-Contributing pull requests are gladly welcomed for this repository. If you are planning a big change, please start a discussion first to make sure we'll be able to merge it.
+Contributing pull requests are gladly welcomed for this repository. If you are planning a significant change, please start a discussion first to ensure we can merge it.
 
 You can also open an [issue](https://github.com/aristanetworks/ansible-cvp/issues) to report any problem or to submit enhancement.