Merge pull request #167 from opsmill/develop

New docs system

Author: BeArchiTek

.dockerignore

@@ -5,5 +5,5 @@ docker-compose.yml
 .venv
 .vscode/
 .github/
-.ruff_cache
 **/.ruff_cache
+**/.DS_Store

.github/build-docs.sh

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

.github/file-filters.yml

@@ -18,3 +18,15 @@ yaml_all: &yaml_all
 ansible_all:
   - *ansible_plugins
   - *ansible_docs
+
+doc_files: &doc_files
+  - "docs/**"
+  - package.json
+  - package-lock.json
+
+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/sync-docs.yml

@@ -0,0 +1,38 @@
+---
+# yamllint disable rule:truthy rule:truthy rule:line-length
+name: Sync Docs Folders
+on:
+  push:
+    branches:
+      - stable
+    paths:
+      - 'docs/docs/**'
+      - 'docs/sidebars.ts'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source repository
+        uses: actions/checkout@v4
+        with:
+          path: source-repo
+
+      - name: Checkout target repository
+        uses: actions/checkout@v4
+        with:
+          repository: opsmill/infrahub-docs
+          token: ${{ secrets.GH_INFRAHUB_BOT_TOKEN }}
+          path: target-repo
+
+      - name: Sync folders
+        run: |
+          rm -rf target-repo/docs/docs-ansible/*
+          rm -f target-repo/docs/sidebars-ansible.ts
+          cp -r source-repo/docs/docs/* target-repo/docs/docs-ansible/
+          cp source-repo/docs/sidebars.ts target-repo/docs/sidebars-ansible.ts
+          cd target-repo
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add .
+          if ! (git diff --quiet && git diff --staged --quiet); then git commit -m "Sync docs from infrahub-ansible repo" && git push; fi

.github/workflows/trigger-push-stable.yml

@@ -51,7 +51,6 @@ jobs:
           virtualenvs-in-project: true
           installer-parallel: true
 
-
       - uses: actions/checkout@v4
         with:
           token: ${{ secrets.GH_INFRAHUB_BOT_TOKEN }}

.github/workflows/workflow-changelog-and-docs.yml

@@ -19,39 +19,39 @@ jobs:
           token: ${{ secrets.GH_INFRAHUB_BOT_TOKEN }}
           fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: "Set up Python"
+        uses: "actions/setup-python@v5"
         with:
-          python-version: 3.11
+          python-version: "3.11"
 
       - name: Install antsibull-changelog, antsichaut
-        run: python -m pip install toml invoke antsibull-changelog antsibull-docs antsichaut --disable-pip-version-check
-
-      - name: Install pandoc
-        run: sudo apt-get install pandoc
+        run: python -m pip install toml invoke --disable-pip-version-check
 
       - name: "Generate Docs"
         run: "invoke generate-doc"
 
-      - name: Generate new version in changelog.yaml
-        run: antsibull-changelog release -v --version "${{ inputs.version }}"
-
-      - name: Generate changelog.yaml
-        run: antsichaut
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SINCE_VERSION: "${{ steps.previoustag.outputs.tag }}"
-
-      - name: Update Changelog.rst
-        run: antsibull-changelog generate -v
+      - name: Sync folders
+        run: |
+          rm -rf target-repo/docs/docs-ansible/*
+          rm -f target-repo/docs/sidebars-ansible.ts
+          cp -r source-repo/docs/docs/* target-repo/docs/docs-ansible/
+          cp source-repo/docs/sidebars.ts target-repo/docs/sidebars-ansible.ts
+          cd target-repo
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add .
+          if ! (git diff --quiet && git diff --staged --quiet); then
+            git commit -m "Sync docs from infrahub-ansible repo"
+            git push
+          fi
 
       - name: commit changelog and docs
         uses: github-actions-x/[email protected]
         with:
           github-token: ${{ secrets.GH_INFRAHUB_BOT_TOKEN }}
           push-branch: 'stable'
           commit-message: 'chore: update changelog & docs'
-          files: docs/ CHANGELOG.rst changelogs/
+          files: docs/
           name: opsmill-bot
           email: [email protected]
           rebase: true

.github/workflows/workflow-linter.yml

@@ -14,6 +14,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  VALE_VERSION: "3.7.1"
+  YAMLLINT_VERSION: "1.35.1"
+
 jobs:
   files-changed:
     name: Detect which file has changed
@@ -22,6 +26,7 @@ jobs:
     outputs:
       python: ${{ steps.changes.outputs.python_all }}
       yaml: ${{ steps.changes.outputs.yaml_all }}
+      documentation: ${{ steps.changes.outputs.documentation_all }}
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
@@ -49,33 +54,108 @@ jobs:
               - '**.yml'
               - '**.yaml'
       - name: "Setup environment"
-        run: "pip install yamllint==1.29.0"
+        run: "pip install yamllint==${{ env.YAMLLINT_VERSION }}"
       - name: "Linting: yamllint"
         run: "yamllint ."
 
   python-lint:
     if: needs.files-changed.outputs.python == 'true'
     needs: ["files-changed"]
     runs-on: "ubuntu-22.04"
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+        poetry-version:
+          - "1.8.5"
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
-      - name: "Setup environment"
-        run: "pip install ruff==0.9.1"
+
+      - name: "Set up Python ${{ matrix.python-version }}"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: "Install Poetry ${{ matrix.poetry-version }}"
+        uses: "snok/install-poetry@v1"
+        with:
+          version: ${{ matrix.poetry-version }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+      - name: "Setup Python environment"
+        run: |
+          poetry config virtualenvs.create true --local
+          poetry env use ${{ matrix.python-version }}
+      - name: "Install dependencies"
+        run: "poetry install --no-interaction --no-ansi --with dev"
+
       - name: "Linting: ruff check"
-        run: "ruff check ."
+        run: "poetry run ruff check ."
       - name: "Linting: ruff format"
-        run: "ruff format --check --diff ."
+        run: "poetry run ruff format --check --diff ."
 
   ansible-lint:
     name: ansible-lint
     runs-on: "ubuntu-22.04"
     steps:
-      # Important: This sets up your GITHUB_WORKSPACE environment variable
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Run ansible-lint
         uses: ansible/ansible-lint-action@v6
+
+  documentation-lint:
+    defaults:
+      run:
+        working-directory: ./docs
+    if: 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 docusaurus"
+
+  validate-documentation-style:
+    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
+
+      # 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" \
+          \) )

.gitignore

@@ -1,16 +1,15 @@
 *.tar.gz
-__pycache__/
+**/__pycache__
 *.pyc
 tests/output/*
 venv/
 .venv/
 .vscode/
 .idea/
-changelogs/.plugin-cache.yaml
 docs/_build/*
 **/.ruff_cache
+**/.DS_Store
 .python-version
-.DS_Store
 
 # https://github.com/ansible/ansible/issues/68499
 # ansible_collections/

.markdownlint.yml

@@ -0,0 +1,16 @@
+---
+default: true
+MD007:
+    indent: 4   # sets indent size to 4 spaces
+MD013: false    # disables max line-length
+MD024: false    # disables 'no duplicate headings',
+                # which we use in tabs for instructions
+MD025:
+    front_matter_title: ""  # prevent collisions with h1s
+                            # and frontmatter titles
+MD029: false    # allows manually creating ordered lists
+MD033: false    # allows inline html to override markdown styles
+MD034: false    # no-bare-urls
+MD045: false    # no alt text around images
+MD047: false    # single trailing newline
+MD014: false    # dollar signs used before commands

.readthedocs.yaml

@@ -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.ini

@@ -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/branded-terms-case-swap.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/colon-space.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/eg-ie.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+[.?!]'