API reference docs (with OpenAPI specs) for Core and Enterprise

.ci/vale/styles/InfluxDB3-Core/Branding.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: Did you mean '%s' instead of '%s'
+level: warning
+ignorecase: false 
+# swap maps tokens in form of bad: good
+  # NOTE: The left-hand (bad) side can match the right-hand (good) side;
+  # Vale ignores alerts that match the intended form.
+swap:
+  'cloud-serverless|cloud-dedicated|clustered': core
+  'Cloud Serverless|Cloud Dedicated|Clustered': Core
+  'API token': database token

.ci/vale/styles/InfluxDB3-Core/v3Schema.yml

@@ -0,0 +1,10 @@
+extends: substitution
+message: Did you mean '%s' instead of '%s'
+level: warning
+ignorecase: false 
+# swap maps tokens in form of bad: good
+  # NOTE: The left-hand (bad) side can match the right-hand (good) side;
+  # Vale ignores alerts that match the intended form.
+swap:
+  '(?i)bucket': database
+  '(?i)measurement': table

.frontmatter-schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Title of the page"
+    },
+    "description": {
+      "type": "string",
+      "description": "Page description that supports multi-line text"
+    },
+    "menu": {
+      "type": "object",
+      "properties": {
+        "influxdb3_core": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Menu item name"
+            }
+          },
+          "required": ["name"]
+        }
+      }
+    },
+    "weight": {
+      "type": "integer",
+      "description": "Order weight for menu items",
+      "minimum": 0
+    },
+    "source": {
+      "type": "string",
+      "description": "Path to source content file",
+      "pattern": "^/shared/.+\\.md$"
+    }
+  },
+  "required": ["title", "description", "menu", "weight"]
+}

.gitignore

@@ -8,7 +8,7 @@ node_modules
 *.log
 /resources
 .hugo_build.lock
-/content/influxdb/*/api/**/*.html
+/content/influxdb*/**/api/**/*.html
 /api-docs/redoc-static.html*
 .vscode/*
 .idea

.vscode/settings.json

@@ -1,4 +1,17 @@
 {
-    "vale.valeCLI.config": " \"${workspaceFolder}/.vale.ini\"",
+    "commentAnchors.tags.anchors": 
+      { "SOURCE": {
+        "scope": "file",
+        "behavior": "link",
+        "iconColor": "#FF0000",
+        "highlightColor": "#FF0000",
+        "style": "bold"
+      }},
+    "commentAnchors.workspace.matchFiles": "**/*.{md,ini,json,yaml,yml}",
+    "commentAnchors.workspace.enabled": true,
+    "yaml.schemas": {
+        "./.frontmatter-schema.json": "${workspaceFolder}/content/**/*.md"
+    },
+    "vale.valeCLI.config": "${workspaceFolder}/.vale.ini",
     "vale.valeCLI.minAlertLevel": "warning",
 }

CONTRIBUTING.md

@@ -46,9 +46,10 @@ To install dependencies listed in package.json:
 4. Install the Yarn package manager and run `yarn` to install project dependencies.
 
 `package.json` contains dependencies for linting and running Git hooks.
+docs-v2 uses [Lefthook](https://github.com/evilmartians/lefthook) to configure and manage pre-commit hooks for linting and testing Markdown content.
+
+Other dependencies used in the project:
 
-- **[husky](https://github.com/typicode/husky)**: manages Git hooks, including the pre-commit hook for linting and testing
-- **[lint-staged](https://github.com/lint-staged/lint-staged)**: passes staged files to commands
 - **[prettier](https://prettier.io/docs/en/)**: formats code, including Markdown, according to style rules for consistency
 
 ### Install Docker
@@ -65,13 +66,24 @@ The tests defined in `compose.yaml` use the dependencies and execution
 environment from this image.
 
 ```bash
-docker build -t influxdata:docs-pytest -f Dockerfile.pytest .
+docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .
 ```
 
 ### Run the documentation locally (optional)
 
 To run the documentation locally, follow the instructions provided in the README.
 
+### Install Visual Studio Code extensions
+
+If you use Microsoft Visual Studio (VS) Code, you can install extensions
+to help you navigate, check, and edit files.
+
+docs-v2 contains a `./.vscode/settings.json` that configures the following extensions:
+
+- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments.
+- Vale: shows linter errors and suggestions in the editor.
+- YAML Schemas: validates frontmatter attributes.
+
 ### Make your changes
 
 Make your suggested changes being sure to follow the [style and formatting guidelines](#style--formatting) outline below.
@@ -80,27 +92,25 @@ Make your suggested changes being sure to follow the [style and formatting guide
 
 ### Automatic pre-commit checks
 
-docs-v2 uses Husky to manage Git hook scripts.
-When you try to commit your changes (for example, `git commit`), Git runs
-scripts configured in `.husky/pre-commit`, including linting and tests for your **staged** files.
+docs-v2 uses Lefthook to manage Git hooks, such as pre-commit hooks that lint Markdown and test code blocks.
+When you try to commit changes (`git commit`), Git runs
+the commands configured in `lefthook.yml` which pass your **staged** files to Vale, Prettier, and Pytest (in a Docker container).
 
 ### Skip pre-commit hooks
 
 **We strongly recommend running linting and tests**, but you can skip them
 (and avoid installing dependencies)
-by including the `HUSKY=0` environment variable or the `--no-verify` flag with
+by including the `LEFTHOOK=0` environment variable or the `--no-verify` flag with
 your commit--for example:
 
 ```sh
 git commit -m "<COMMIT_MESSAGE>" --no-verify
 ```
 
 ```sh
-HUSKY=0 git commit
+LEFTHOOK=0 git commit
 ```
 
-For more options, see the [Husky documentation](https://typicode.github.io/husky/how-to.html#skipping-git-hooks).
-
 ### Set up test scripts and credentials
 
 To set up your docs-v2 instance to run tests locally, do the following:

Dockerfile.pytest

@@ -32,7 +32,13 @@ RUN apt-get update && apt-get upgrade -y && apt-get install -y \
   python3-venv \
   rsync \
   telegraf \
-  wget
+  wget \
+  yq
+
+# Install InfluxDB 3 Core
+RUN curl -O https://www.influxdata.com/d/install_influxdb3.sh \
+&& chmod +x install_influxdb3.sh \
+&& bash -c yes | ./install_influxdb3.sh
 
 RUN ln -s /usr/bin/python3 /usr/bin/python
 

api-docs/README.md

@@ -237,7 +237,7 @@ InfluxDB Cloud releases are frequent and not versioned, so the Cloud API spec is
 We regenerate API reference docs from `influxdata/openapi`
 **master** branch as features are released.
 
-### InfluxDB OSS version
+### InfluxDB OSS v2 version
 
  Given that
  `influxdata/openapi` **master** may contain OSS spec changes not implemented

api-docs/generate-api-docs.sh

@@ -41,7 +41,6 @@ function generateHtml {
   local productName="$3"
   local api="$4"
   local configPath="$5"
-  local isDefault=$6
 
   # Use the product name to define the menu for the Hugo template
   local menu="$(echo $productVersion | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
@@ -55,12 +54,23 @@ function generateHtml {
   # Use the title and summary defined in the product API's info.yml file.
   local title=$(yq '.title' $productVersion/$apiName/content/info.yml)
   local menuTitle=$(yq '.x-influxdata-short-title' $productVersion/$apiName/content/info.yml)
-  local description=$(yq '.summary' $productVersion/$apiName/content/info.yml)
+  # Get the shortened description to use for metadata.
+  local shortDescription=$(yq '.x-influxdata-short-description' $productVersion/$apiName/content/info.yml)
+  # Get the aliases array from the configuration file.
+  local aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
+  # If aliases is null, set it to an empty YAML array. 
+  if [[ "$aliases" == "null" ]]; then
+    aliases='[]'
+  fi
+  local weight=102
+  if [[ $apiName == "v1-compatibility" ]]; then
+    weight=304
+  fi
   # Define the file name for the Redoc HTML output.
   local specbundle=redoc-static_index.html
   # Define the temporary file for the Hugo template and Redoc HTML.
   local tmpfile="${productVersion}-${api}_index.tmp"
-
+  
   echo "Bundling $specPath"
 
   # Use npx to install and run the specified version of redoc-cli.
@@ -70,75 +80,31 @@ function generateHtml {
   npm_config_yes=true npx [email protected] bundle $specPath \
   --config $configPath \
   -t template.hbs \
-  --title=$title \
+  --title="$title" \
   --options.sortPropsAlphabetically \
   --options.menuToggle \
   --options.hideDownloadButton \
   --options.hideHostname \
   --options.noAutoAuth \
   --output=$specbundle \
-  --templateOptions.description=$description \
+  --templateOptions.description="$shortDescription" \
   --templateOptions.product="$productVersion" \
   --templateOptions.productName="$productName"
 
-  if [[ $apiName == "v1-compatibility" ]]; then
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 304
-aliases:
-  - /influxdb/$versionDir/api/v1/
----
-"
-  elif [[ $apiVersion == "0" ]]; then
-  echo $productName $apiName
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-weight: 102
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
+  local frontmatter=$(yq eval -n \
+      ".title = \"$title\" |
+       .description = \"$shortDescription\" |
+       .layout = \"api\" |
+       .weight = $weight |
+       .menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
+       .menu.[\"$menu\"].name = \"$menuTitle\" |
+       .menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
+      .aliases = \"$aliases\"")
+
+  frontmatter="---
+$frontmatter
 ---
 "
-  elif [[ $isDefault == true ]]; then
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
-aliases:
-  - /influxdb/$versionDir/api/
----
-"
-  else
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
----
-"
-  fi
 
   # Create the Hugo template file with the frontmatter and Redoc HTML
   echo "$frontmatter" >> $tmpfile
@@ -174,9 +140,10 @@ function build {
     # Get the version API configuration file.
     local configPath="$version/.config.yml"
     if [ ! -f "$configPath" ]; then
-      configPath=".config.yml"
+     # Skip to the next version if the configuration file doesn't exist.
+      continue  
     fi
-    echo "Using config $configPath"
+    echo "Using config $version $configPath"
     # Get the product name from the configuration.
     local versionName
     versionName=$(yq e '.x-influxdata-product-name' "$configPath")
@@ -198,13 +165,7 @@ function build {
       if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
         echo "OpenAPI spec $specPath doesn't exist."
       fi
-      # Get default status from the configuration.
-      local isDefault=false
-      local defaultStatus
-      defaultStatus=$(yq e ".apis | .$api | .x-influxdata-default" "$configPath")
-      if [[ $defaultStatus == "true" ]]; then
-        isDefault=true
-      fi
+
 
       # If the spec file differs from master, regenerate the HTML.
       local update=0
@@ -218,9 +179,9 @@ function build {
 
       if [[ $update -eq 0 ]]; then
         echo "Regenerating $version $api"
-        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath" "$isDefault"
+        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath"
       fi
-      echo "========Done with $version $api========"
+      echo -e "========Finished $version $api========\n\n"
     done <<< "$apis"
   done
 }