Doc: Contribution Guide Updates (aristanetworks#3766)

Co-authored-by: Claus Holbech <[email protected]> Co-authored-by: JulioPDX <[email protected]> Co-authored-by: Alexey Gorbunov <[email protected]>
Vibhu-gslab · May 31, 2024 · 1c00222 · 1c00222
1 parent 7525171
commit 1c00222
Show file tree

Hide file tree

Showing 21 changed files with 314 additions and 930 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,20 +5,24 @@ repos:
     rev: v4.6.0
     hooks:
       - id: trailing-whitespace
+        name: Trims trailing whitespace.
         exclude: ansible_collections/arista/avd/molecule
       - id: end-of-file-fixer
+        name: Ensures that a file is either empty, or ends with one newline.
         exclude_types: [svg, json]
         exclude: ansible_collections/arista/avd/molecule
       - id: check-added-large-files
+        name: Prevents giant files from being committed.
         exclude: (ansible_collections/arista/avd/molecule|pickle$)
       - id: check-merge-conflict
+        name: Checks for files that contain merge conflict strings.
         exclude: ansible_collections/arista/avd/molecule
 
   - repo: https://github.com/Lucas-C/pre-commit-hooks
     rev: v1.5.5
     hooks:
-      - name: Check and insert license on Python files
-        id: insert-license
+      - id: insert-license
+        name: Check and insert license on Python files.
         exclude: ansible_collections/arista/avd/(plugins/module_utils|tests/unit(/module_utils|/modules|))/__init__.py
         files: .*\.py$
         args:
@@ -29,8 +33,8 @@ repos:
           - --fuzzy-match-generates-todo
           - --no-extra-eol
 
-      - name: Check and insert license on select YAML files
-        id: insert-license
+      - id: insert-license
+        name: Check and insert license on select YAML files.
         files: ansible_collections/arista/avd/roles/.*/(handlers|schemas|tasks)/.*\.yml$
         args:
           - --license-filepath
@@ -40,8 +44,8 @@ repos:
           - --fuzzy-match-generates-todo
           - --no-extra-eol
 
-      - name: Check and insert license on Jinja2 files
-        id: insert-license
+      - id: insert-license
+        name: Check and insert license on Jinja2 files.
         files: .*\.j2$
         exclude: ansible_collections/arista/avd/molecule.*
         args:
@@ -54,8 +58,8 @@ repos:
           - '{#||#}'
           - --no-extra-eol
 
-      - name: Check and insert license on Markdown files
-        id: insert-license
+      - id: insert-license
+        name: Check and insert license on Markdown files.
         files: .*\.md$
         exclude: (ansible_collections/arista/avd/molecule|.github|ansible_collections/arista/avd/examples/.+/documentation/).*
         args:
@@ -76,19 +80,19 @@ repos:
     rev: 5.13.2
     hooks:
       - id: isort
-        name: Check for changes when running isort on all python files
+        name: Check for changes when running isort on all python files.
 
   - repo: https://github.com/psf/black
     rev: 24.4.2
     hooks:
       - id: black
-        name: Check for changes when running Black on all python files
+        name: Check for changes when running Black on all python files.
 
   - repo: https://github.com/pycqa/flake8
     rev: 7.0.0
     hooks:
       - id: flake8
-        name: Check for Flake8 errors on Python files
+        name: Check for Flake8 errors on Python files.
         # ignoring errors and selecting line length as per
         # https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_util/controller/sanity/pep8/current-ignore.txt
         types: [python]
@@ -99,7 +103,7 @@ repos:
     rev: "v3.1.1"
     hooks:
       - id: pylint # Use pylintrc file in repository
-        name: Check for Linting errors on Python files
+        name: Check for Linting errors on Python files with settings defined in `pylintrc`.
         description: This hook runs pylint.
         types: [python]
         args:
@@ -110,7 +114,7 @@ repos:
     rev: "v1.35.1"
     hooks:
       - id: yamllint
-        name: Check for Linting errors on YAML files
+        name: Check for Linting errors on YAML files with settings defined in `.github/yamllintrc`.
         description: This hook runs yamllint.
         entry: yamllint
         language: python
@@ -154,47 +158,47 @@ repos:
     hooks:
 
       - id: docs-plugin-modules
-        name: Build documentation for collection modules and action plugins
+        name: Build documentation for collection modules and action plugins.
         entry: ansible-doc-extractor --template ansible_collections/arista/avd/docs/templates/plugin-docs.j2 --markdown "ansible_collections/arista/avd/docs/plugins/Modules_and_action_plugins/"
         language: python
         types: [python]
         additional_dependencies: ['ansible-doc-extractor>=0.1.10', 'ansible-core>=2.15.0,<2.18.0']
         files: ansible_collections/arista/avd/plugins/modules/
 
       - id: docs-plugin-filter
-        name: Build documentation for collection filter plugins
+        name: Build documentation for collection filter plugins.
         entry: ansible-doc-extractor --template ansible_collections/arista/avd/docs/templates/plugin-docs.j2 --markdown "ansible_collections/arista/avd/docs/plugins/Filter_plugins/"
         language: python
         types: [python]
         additional_dependencies: ['ansible-doc-extractor>=0.1.10', 'ansible-core>=2.15.0,<2.18.0']
         files: ansible_collections/arista/avd/plugins/filter/
 
       - id: docs-plugin-lookup
-        name: Build documentation for collection lookup plugins
+        name: Build documentation for collection lookup plugins.
         entry: ansible-doc-extractor --template ansible_collections/arista/avd/docs/templates/plugin-docs.j2 --markdown "ansible_collections/arista/avd/docs/plugins/Lookup_plugins/"
         language: python
         types: [python]
         additional_dependencies: ['ansible-doc-extractor>=0.1.10', 'ansible-core>=2.15.0,<2.18.0']
         files: ansible_collections/arista/avd/plugins/lookup/
 
       - id: docs-plugin-test
-        name: Build documentation for collection test plugins
+        name: Build documentation for collection test plugins.
         entry: ansible-doc-extractor --template ansible_collections/arista/avd/docs/templates/plugin-docs.j2 --markdown "ansible_collections/arista/avd/docs/plugins/Test_plugins/"
         language: python
         types: [python]
         additional_dependencies: ['ansible-doc-extractor>=0.1.10', 'ansible-core>=2.15.0,<2.18.0']
         files: ansible_collections/arista/avd/plugins/test/
 
       - id: docs-plugin-vars
-        name: Build documentation for collection var plugins
+        name: Build documentation for collection var plugins.
         entry: ansible-doc-extractor --template ansible_collections/arista/avd/docs/templates/plugin-docs.j2 --markdown "ansible_collections/arista/avd/docs/plugins/Vars_plugins/"
         language: python
         types: [python]
         additional_dependencies: ['ansible-doc-extractor>=0.1.10', 'ansible-core>=2.15.0,<2.18.0']
         files: ansible_collections/arista/avd/plugins/vars/
 
       - id: schemas
-        name: Build AVD Schemas and Docs
+        name: Build AVD schemas and documentation.
         entry: sh -c 'exec python-avd/scripts/build-schemas.py'
         language: python
         files: ansible_collections/arista/avd/roles/[a-z_]+/schemas
@@ -205,7 +209,7 @@ repos:
     rev: v0.41.0
     hooks:
       - id: markdownlint
-        name: Check for Linting errors on MarkDown files
+        name: Check for Linting errors on Markdown files with settings defined in `.github/.markdownlint.yaml`.
         args:
           - --config=.github/.markdownlint.yaml
           - --ignore-path=.github/.markdownlintignore

diff --git a/Dockerfile b/Dockerfile
diff --git a/Makefile b/Makefile
@@ -1,37 +1,37 @@
 CURRENT_DIR = $(shell pwd)
-# option to run ansible-test sanity: must be either venv or docker (default is docker)
-ANSIBLE_TEST_MODE ?= docker
+# option to run ansible-test sanity: must be either venv or docker (default is venv)
+ANSIBLE_TEST_MODE ?= venv
 MUFFET_TIMEOUT ?= 60
 
 .PHONY: help
 help: ## Display help message
 	@grep -E '^[0-9a-zA-Z_-]+\.*[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 #########################################
-# Ansible Collection actions		#
+# Ansible Collection actions            #
 #########################################
 .PHONY: collection-build
-collection-build: ## Build arista.cvp collection locally
+collection-build: ## Build arista.avd collection locally.
 	./python-avd/scripts/build-schemas.py
 	ansible-galaxy collection build --force ansible_collections/arista/avd
 
 #########################################
-# pyavd actions                 #
+# pyavd actions                         #
 #########################################
 .PHONY: pyavd-build
-pyavd-build: ## Build PyAVD Python package locally
+pyavd-build: ## Build PyAVD Python package locally.
 	cd python-avd && $(MAKE) clean build
 
 .PHONY: pyavd-test
-pyavd-test: ## Test PyAVD Python code
+pyavd-test: ## Test PyAVD Python code with tox.
 	cd python-avd && $(MAKE) clean && tox -r
 
 .PHONY: pyavd-publish
-pyavd-publish: ## Build and publish PyAVD Python package
+pyavd-publish: ## Build and publish PyAVD Python package.
 	cd python-avd && $(MAKE) clean build publish
 
 .PHONY: pyavd-install
-pyavd-install: pyavd-build ## Build and install PyAVD Python package
+pyavd-install: pyavd-build ## Build and install PyAVD Python package.
 	pip install python-avd/dist/*
 
 # The editable_mode=compat is required for pylance to pick up the editable install.
@@ -47,21 +47,21 @@ pyavd-editable-install: ## Build and install PyAVD as editable
 sanity: sanity-info sanity-lint sanity-import ## Run ansible-test sanity validation.
 
 .PHONY: sanity-info
-sanity-info: ## Show information about ansible-test
+sanity-info: ## Show information about ansible-test.
 	cd ansible_collections/arista/avd/ ; ansible-test env
 
 .PHONY: sanity-lint
-sanity-lint: ## Run ansible-test sanity for code sanity
+sanity-lint: ## Run ansible-test sanity for code sanity. Specify `ANSIBLE_TEST_MODE=<venv|docker>` (default: `venv`).
 	cd ansible_collections/arista/avd/ ; \
 	ansible-test sanity --requirements --$(ANSIBLE_TEST_MODE) --skip-test import
 
 .PHONY: sanity-import
-sanity-import: ## Run ansible-test sanity for code import
+sanity-import: ## Run ansible-test sanity for code import. Specify `ANSIBLE_TEST_MODE=<venv|docker>` (default: `venv`).
 	cd ansible_collections/arista/avd/ ; \
 	ansible-test sanity --requirements --$(ANSIBLE_TEST_MODE) --test import
 
 .PHONY: galaxy-importer
-galaxy-importer:  ## Run galaxy importer tests
+galaxy-importer:  ## Run galaxy importer tests.
 	rm -f *.tar.gz && \
 	ansible-galaxy collection build --force ansible_collections/arista/avd && \
 	python -m galaxy_importer.main *.tar.gz
@@ -71,7 +71,7 @@ galaxy-importer:  ## Run galaxy importer tests
 #############################################
 
 .PHONY: unit-tests
-unit-tests: ## Run unit test cases using ansible-test
+unit-tests: ## Run unit test cases using ansible-test. Specify `ANSIBLE_TEST_MODE=<venv|docker>` (default: `venv`).
 	cd ansible_collections/arista/avd/ ; \
 	ansible-test units --requirements --$(ANSIBLE_TEST_MODE) -vv
 
@@ -80,26 +80,6 @@ unit-tests: ## Run unit test cases using ansible-test
 ###################################################
 
 .PHONY: integration-tests
-integration-tests: ## Run integration test cases using ansible-test
+integration-tests: ## Run integration test cases using ansible-test. Specify `ANSIBLE_TEST_MODE=<venv|docker>` (default: `venv`).
 	cd ansible_collections/arista/avd/ ; \
 	ansible-test integration --requirements --$(ANSIBLE_TEST_MODE)
-
-#########################################
-# Documentation actions					#
-#########################################
-.PHONY: webdoc-up
-webdoc-up: ## Build documentation to view
-	docker-compose -f development/docker-compose.yml up -d webdoc_avd ; \
-	docker exec -it webdoc_avd sh
-
-.PHONY: webdoc-down
-webdoc-down: ## shutdown docs
-	docker-compose -f development/docker-compose.yml down
-
-.PHONY: webdoc-logs
-webdoc-logs: ## View logs
-	docker logs webdoc_avd
-
-.PHONY: check-avd-404
-check-avd-404: ## Check local 404 links for AVD documentation
-	docker run --rm --network container:webdoc_avd raviqqe/muffet:2.9.2 http://127.0.0.1:8000/ -e ".*fonts.googleapis.com.*" -e ".*fonts.gstatic.com.*" -e ".*tools.ietf.org.*" -e ".*edit.*" -e ".*docs.github.com.*" -e "twitter.com" -f --max-redirections=3 --timeout=$(MUFFET_TIMEOUT) --rate-limit=1 --buffer-size 8192