Merge branch 'ClickHouse:main' into experiment_vertical_stepper

Author: Blargian

.github/workflows/trigger-build.yml

@@ -0,0 +1,76 @@
+name: Style check
+
+on:
+  pull_request:
+    types:
+      - synchronize
+      - reopened
+      - opened
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          path: .
+
+      - name: Install Vale
+        run: |
+          sudo snap install vale
+          vale -v # Verify installation
+
+      - name: Set up Python
+        run: |
+          curl -Ls https://astral.sh/uv/install.sh | sh
+          uv python install 3.12
+
+      - name: Log changed lines
+        run: |
+          # Make sure script is executable
+          chmod +x scripts/vale/changed_lines_to_json.py
+          
+          # Run the script to get changed lines
+          python scripts/vale/changed_lines_to_json.py ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}
+          
+          # Check if the report was created
+          if [ -f "logs/changed_lines.json" ]; then
+            echo "Changed lines log generated successfully."
+          else
+            echo "Error: Failed to generate changed lines report."
+            exit 1
+          fi
+
+      - name: Run vale on changed files
+        run: |
+          # Extract file names from the JSON report
+          CHANGED_FILES=$(cat logs/changed_lines.json | jq -r '.[].filename' | tr '\n' ' ')
+
+          # Check if we have any files to process
+          if [ -z "$CHANGED_FILES" ]; then
+            echo "No changed files to analyze"
+            exit 0
+          fi
+
+          echo "Running Vale on: $CHANGED_FILES"
+          vale --config='.vale.ini' \
+          ${CHANGED_FILES} \
+          --output=scripts/vale/vale_output_template.tmpl --no-exit > logs/vale_output.log
+
+      - name: Parse Vale output
+        run: |
+          # Read the changed_lines.json to get line numbers
+          CHANGED_LINES=$(cat logs/changed_lines.json)
+
+          # Run the parser script
+          python scripts/vale/vale_annotations.py --git-log-file="logs/changed_lines.json" --vale-log-file="logs/vale_output.log"

.github/workflows/vale-linter.yml

@@ -57,7 +57,7 @@ docs/about-us/beta-and-experimental-features.md
 
 **.translated
 **.translate
-ClickHouse/
+/ClickHouse/
 
 
 # Ignore table of contents files

.gitignore

@@ -0,0 +1,5 @@
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[*.{md}]
+BasedOnStyles = ClickHouse

.vale.ini

@@ -43,7 +43,7 @@ sudo apt-get install npm
 sudo npm install --global yarn
 ```
 
-note: if the Node version available in your distro is old (`<=v16`), you can use [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to pick a specific one.
+Note: if the Node version available in your distro is old (`<=v16`), you can use [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to pick a specific one.
 
 for example to use the appropriate version of node:
 

contribute/contrib-writing-guide.md

@@ -251,3 +251,128 @@ should pass. Finally open another PR on the docs repo again to remove the
 file from the exception list and add it to `sidebars.js` in the appropriate
 sidebar.
 
+## Client versioning
+
+### Background
+
+Docusaurus supports versioning documentation, however it is opinionated and 
+aimed more at use cases where you have a single product with set releases, or
+multiple products with their own releases.
+
+Due to the fact that we have many different integrations in ClickHouse, each of 
+which may need versioned documentation, we use the following custom 
+`ClientVersionDropdown` component for versioning of client documentation:
+
+```markdown
+<ClientVersionDropdown versions={}/>
+```
+
+### How to use it 
+
+Versioned folders are structured as follows:
+
+```text
+.
+├── client
+│         ├── _snippets
+│         │         ├── _v0_7.mdx
+│         │         └── _v0_8.mdx
+│         └── client.mdx
+├── index.md
+├── jdbc
+│         ├── _snippets
+│         │         ├── _v0_7.mdx
+│         │         └── _v0_8.mdx
+│         └── jdbc.mdx
+└── r2dbc.md
+```
+
+* The content for each version is placed in a snippet. For example `_v0_7.mdx`
+  * Snippets begin with `_` 
+  * Snippets do not contain front-matter
+  * These snippets import any components they may need (See `_v0_7.mdx` for example)
+  * They should be .mdx files
+* There is a single page for all versions. For example `client.mdx`
+  * This page contains frontmatter
+  * It imports the `<ClientVersionDropdown>` component
+  * It should be a .mdx file
+
+To use this component, import it into the single page:
+
+```js
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'
+```
+
+Also import the two snippets:
+
+```js
+import v07 from './_v0_7.mdx'
+import v08 from './_v0_8.mdx'
+```
+
+Pass it an array of objects representing versions and their respective snippets:
+
+```markdown
+<ClientVersionDropdown versions={[
+{
+'version': 'v0.8+',
+'snippet': v08
+},
+{
+'version': 'v0.7.x',
+'snippet': v07
+}
+]}/>
+```
+
+**Note**: The component will display the first item as the 'selected' version, so
+it is important to make sure the order of the objects is correct.
+
+### URL parameters
+
+If you need to share a link to the page you can do it through URL params:
+
+```response
+/docs/integrations/language-clients/java/client?v=v08
+```
+
+When using URL parameters to control which version of documentation is displayed, 
+there are conventions to follow for reliable functionality. 
+Here's how the `?v=v08` parameter relates to the snippet selection:
+
+#### How It Works
+
+The URL parameter acts as a selector that matches against the `version` property 
+in your component configuration. For example:
+
+- URL: `docs/api?v=v08`
+- Matches: `version: 'v0.8+'` in your dropdown configuration
+
+#### Conventions That Work
+
+- **Simple Version Strings**: Parameters like `?v=v08`, `?v=v07` work by 
+- matching against stripped versions of your configured version names.
+
+- **Flexible Matching**: The implementation supports:
+  - Removing dots: `v0.8` matches `?v=v08`
+  - Ignoring plus signs: `v0.8+` matches `?v=v08`
+  - Case-insensitive matching: `v0.8` matches `?v=V08`
+
+- **Preserving Other Parameters**: Other URL parameters are preserved when 
+switching versions.
+
+#### What Won't Work
+
+- **Partial Matches**: `?v=8` won't match `v0.8` with the default implementation.
+
+- **Complex Version Strings**: Very complex versions like `?v=v1.2.3-beta.4` 
+require more sophisticated matching logic. (Reach out to the docs team if required)
+
+- **Non-Standard Formats**: Version formats not accounted for in the matching 
+logic might fail.
+
+#### Best Practices
+
+1. Keep version strings in consistent formats for predictable results.
+
+2. Use simplified version parameters in URLs (e.g., `v08` instead of `v0.8.x`).