update readme (#122)

* update readme
* fix ci
* add vale config
* chmod file

.github/build-docs.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+cd docs && npm install && npm run build

.github/file-filters.yml

@@ -0,0 +1,25 @@
+---
+ci_config: &ci_config
+  - ".github/workflows/ci.yml"
+  - ".github/file-filters.yml"
+
+github_workflows: &github_workflows
+  - ".github/workflows/*.yml"
+
+doc_files: &doc_files
+  - "docs/**"
+  - package.json
+  - package-lock.json
+
+python_all: &python_all
+  - "**/*.py"
+
+yaml_all: &yaml_all
+  - "**/*.{yml,yaml}"
+
+markdown_all: &markdown_all
+  - "**/*.{md,mdx}"
+
+documentation_all:
+  - *doc_files
+  - *markdown_all

.github/labeler.yml

@@ -0,0 +1,8 @@
+---
+"group/ci":
+  - changed-files:
+      - any-glob-to-any-file: [".github/**"]
+
+"type/documentation":
+  - changed-files:
+      - any-glob-to-any-file: ["docs/**"]

.github/workflows/ci.yml

@@ -11,19 +11,31 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  VALE_VERSION: "3.7.1"
+
 jobs:
-  yaml-lint:
-    runs-on: "ubuntu-latest"
+  files-changed:
+    name: Detect which file has changed
+    runs-on: ubuntu-latest
     timeout-minutes: 5
+    outputs:
+      documentation: ${{ steps.changes.outputs.documentation_all }}
+      python: ${{ steps.changes.outputs.python_all }}
+      yaml: ${{ steps.changes.outputs.yaml_all }}
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
-      - name: "Setup environment"
-        run: "pip install yamllint==1.35.1"
-      - name: "Linting: yamllint"
-        run: "yamllint -s ."
+      - name: Check for file changes
+        uses: opsmill/paths-filter@v3.0.2
+        id: changes
+        with:
+          token: ${{ github.token }}
+          filters: .github/file-filters.yml
 
   python-lint:
+    if: needs.files-changed.outputs.python == 'true'
+    needs: ["files-changed"]
     runs-on: "ubuntu-latest"
     strategy:
       matrix:
@@ -63,38 +75,72 @@ jobs:
       - name: "Pylint Tests"
         run: "poetry run pylint emma pages *.py"
 
-  # linter:
-  #   runs-on: "ubuntu-latest"
-  #   timeout-minutes: 5
-  #   env:
-  #     VALIDATE_PYTHON_MYPY: true
-  #     VALIDATE_PYTHON_RUFF: true
-  #     VALIDATE_PYTHON_PYLINT: true
-  #     VALIDATE_YAML: true
-  #     VALIDATE_GITHUB_ACTIONS: true
-  #     PYTHON_MYPY_CONFIG_FILE: pyproject.toml
-  #     PYTHON_RUFF_CONFIG_FILE: pyproject.toml
-  #     MULTI_STATUS: false
-  #   steps:
-  #     - name: Checkout code
-  #       uses: actions/checkout@v4
-  #       with:
-  #         # super-linter needs the full git history to get the
-  #         # list of files that changed across commits
-  #         fetch-depth: 0
+  yaml-lint:
+    if: needs.files-changed.outputs.yaml == 'true'
+    needs: ["files-changed"]
+    runs-on: "ubuntu-latest"
+    timeout-minutes: 5
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+        with:
+          submodules: true
+      - name: "Setup environment"
+        run: "pip install yamllint==1.35.1"
+      - name: "Linting: yamllint"
+        run: "yamllint -s ."
+
+  documentation:
+    defaults:
+      run:
+        working-directory: ./docs
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled') &&
+      needs.files-changed.outputs.documentation == 'true'
+    needs: ["files-changed", "yaml-lint", "python-lint"]
+    runs-on: "ubuntu-22.04"
+    timeout-minutes: 5
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+        with:
+          submodules: true
+      - name: Install NodeJS
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+      - name: "Install dependencies"
+        run: npm install
+      - name: "Setup Python environment"
+        run: "pip install invoke toml"
+      - name: "Build docs website"
+        run: "invoke docs"
 
-  #     - name: Set up Python
-  #       uses: actions/setup-python@v5
-  #       with:
-  #         python-version: "3.12"
-  #     - name: "Setup environment"
-  #       run: |
-  #         pipx install poetry
-  #         poetry config virtualenvs.prefer-active-python true
-  #     - name: "Install Package"
-  #       run: "poetry install"
+  validate-documentation-style:
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled')
+    needs: ["files-changed", "yaml-lint", "python-lint"]
+    runs-on: "ubuntu-22.04"
+    timeout-minutes: 5
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+        with:
+          submodules: true
 
-  #     - name: Super-linter
-  #       uses: super-linter/super-linter/slim@v6.7.0
-  #       env:
-  #         PYTHONPATH: "/github/workspace:/github/workflow/.venv/lib/python3.12/site-packages"
+      # The official GitHub Action for Vale doesn't work, installing manually instead:
+      # https://github.com/errata-ai/vale-action/issues/103
+      - name: Download Vale
+        run: |
+          curl -sL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -o vale.tar.gz
+          tar -xzf vale.tar.gz
+        env:
+          VALE_VERSION: ${{ env.VALE_VERSION }}
+      - name: "Validate documentation style"
+        run: ./vale $(find ./docs -type f \( -name "*.mdx" -o -name "*.md" \) )

.github/workflows/sync-docs.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - 'docs/docs/**'
+      - 'docs/sidebars.ts'
 
 jobs:
   sync:
@@ -26,10 +27,11 @@ jobs:
       - name: Sync folders
         run: |
           rm -rf target-repo/docs/docs-emma/*
+          rm -f target-repo/docs/sidebars-emma.ts
           cp -r source-repo/docs/docs/* target-repo/docs/docs-emma/
+          cp source-repo/docs/sidebars.ts target-repo/docs/sidebars-emma.ts
           cd target-repo
           git config user.name github-actions
           git config user.email github-actions@github.com
           git add .
-          git diff --quiet && git diff --staged --quiet || (git commit -m "Sync folder from source repository" && git push)
-          git diff --quiet && git diff --staged --quiet || (git commit -m "Sync folder from source repository" && git push)
+          if ! (git diff --quiet && git diff --staged --quiet); then git commit -m "Sync docs from infrahub-demo-dc-fabric repo" && git push; fi

.vale.ini

@@ -0,0 +1,15 @@
+StylesPath = .vale/styles
+
+MinAlertLevel = warning
+
+[formats]
+mdx = md
+
+[docs/**/*.md]
+BasedOnStyles = Infrahub
+;(import.*?\n) to ignore import statement in .mdx
+;(```.*?```\n) to ignore code block in .mdx
+BlockIgnores = (?s) *((import.*?\n)|(```.*?```\n))
+
+[*]
+BasedOnStyles = Infrahub

.vale/styles/Infrahub/branded-terms-case-swap.yml

@@ -0,0 +1,14 @@
+---
+extends: substitution
+message: Use '%s' instead of '%s'
+level: error
+ignorecase: false
+action:
+  name: replace
+swap:
+  (?i:[^/]Github): GitHub
+  (?i:gitpod): GitPod
+  (?i:[^/]Graphql): GraphQL
+  infrahub(?:\s|$): Infrahub
+  (?i:Openconfig): OpenConfig
+  opsmill(?:\s|$): OpsMill

.vale/styles/Infrahub/colon-space.yml

@@ -0,0 +1,8 @@
+---
+extends: substitution
+message: "Use a space after a colon, but not before"
+level: warning
+ignorecase: true
+nonword: true
+swap:
+  '(?<=\s):(?=\s+)': ': '

.vale/styles/Infrahub/eg-ie.yml

@@ -0,0 +1,12 @@
+---
+extends: substitution
+message: "Instead of %s, use ',i.e.,' or 'for example:'."
+level: warning
+ignorecase: true
+nonword: true
+action:
+  name: replace
+swap:
+  - e\.g\.: i.e.
+  - e\. g\.: i.e.
+  - i\. e\.: i.e.

.vale/styles/Infrahub/oxford-comma.yml

@@ -0,0 +1,8 @@
+---
+extends: existence
+message: "Use a comma before the last 'and' or 'or' in a list of items."
+level: suggestion
+scope: sentence
+nonword: true
+tokens:
+  - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]'

.vale/styles/Infrahub/sentence-case.yml

@@ -0,0 +1,75 @@
+---
+extends: capitalization
+message: "'%s' should use sentence case"
+level: warning
+scope:
+  - heading.h1
+  - heading.h2
+  - heading.h3
+  - heading.h4
+  - heading.h5
+  - heading.h6
+match: $sentence
+exceptions:
+  - Alpha
+  - Ansible
+  - API
+  - Attributes
+  - AWS S3
+  - Beta
+  - BGP
+  - CA certificates
+  - CI
+  - Codespaces
+  - CoreArtifactTarget
+  - CoreRepository
+  - CoreGroup
+  - Docker Compose
+  - E2E
+  - Generics
+  - Git
+  - GitHub
+  - GitHub Codespaces
+  - GitLab
+  - GitPod
+  - GraphQL
+  - GraphQLQuery
+  - include_in_menu & menu_placement
+  - Helm
+  - High Availability
+  - Human Friendly Identifier
+  - Infrahub
+  - infrahubctl
+  - IPHost
+  - IP
+  - IPAM
+  - IPNetwork
+  - IP Fabric
+  - JavaScript
+  - JetStream
+  - Jinja
+  - Jinja2
+  - JWT
+  - Namespace
+  - NATS
+  - Node
+  - OAuth2
+  - OIDC
+  - Open ID Connect
+  - OpsMill
+  - Pydantic
+  - Python
+  - RabbitMQ
+  - REST
+  - RFile
+  - SDK
+  - Single sign-on
+  - SSO
+  - TLS
+  - Tony Stark
+  - TransformPython
+  - UI
+  - Vale
+  - VS Code
+  - VS Code extensions
+  - WebUI

.vale/styles/Infrahub/simple-easy.yml

@@ -0,0 +1,9 @@
+---
+extends: existence
+message: "Remove %s and avoid words that minimize the effort level required."
+level: warning
+ignorecase: true
+tokens:
+  - easy
+  - simple
+  - simply

.vale/styles/Infrahub/spelling.yml

@@ -0,0 +1,8 @@
+---
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+filters:
+  - '[pP]y.*\b'
+  - '\bimport_.*\b'    # New filter to ignore variables starting with 'import_'
+ignore: spelling-exceptions.txt

.vale/styles/Infrahub/swap.yml

@@ -0,0 +1,10 @@
+---
+extends: substitution
+message: "Use '%s' instead of '%s'"
+level: error
+ignorecase: true
+action:
+  name: replace
+swap:
+  config\b(?!\.\w): configuration
+  repo: repository