From 0fcf2bdd3193704305f3a159ba7b17ff418272e2 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 25 Nov 2025 17:58:29 -0500 Subject: [PATCH] Note excluded internal-use options (#6571) * chore: Standard exclude comment format to denote flags, options, etc. that shouldn't be promoted in docs * chore: exclude internal flags * chore: Add docs:exclude comments for internal CLI flags, fix linting - Note internal options that should be ignored by `docs audit` and authors. - Remove character escaping from GitHub callouts and placeholders Lint config changes: - Add explicit exclude for content/**/*.md in lint-markdown-instructions - Exclude all markdown files from Prettier formatting Fixes issue where remark-lint was auto-formatting content files and escaping special characters like [!Note] callouts and underscores. * fix: cleanup escaping --- .prettierignore | 5 +- DOCS-CONTRIBUTING.md | 72 +++++++++++++++++++ .../core/reference/cli/influxdb3/serve.md | 5 ++ .../reference/cli/influxdb3/serve.md | 5 ++ .../shared/influxdb3-cli/config-options.md | 21 +++--- .../shared/influxdb3-cli/create/database.md | 4 ++ content/shared/influxdb3-cli/create/table.md | 3 + .../shared/influxdb3-cli/create/trigger.md | 4 ++ .../shared/influxdb3-cli/delete/database.md | 4 ++ content/shared/influxdb3-cli/delete/table.md | 4 ++ .../shared/influxdb3-cli/delete/trigger.md | 4 ++ .../shared/influxdb3-cli/install/package.md | 4 ++ lefthook.yml | 12 ++-- 13 files changed, 131 insertions(+), 16 deletions(-) diff --git a/.prettierignore b/.prettierignore index b7974b235..db81a4e08 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,4 +3,7 @@ **/.svn **/.hg **/node_modules -assets/jsconfig.json \ No newline at end of file +assets/jsconfig.json + +# Markdown files - Prettier insists on escaping common formatting +**.md \ No newline at end of file diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md index cceff8c3c..07f1f6ebe 100644 --- a/DOCS-CONTRIBUTING.md +++ b/DOCS-CONTRIBUTING.md @@ -195,6 +195,78 @@ source: /shared/path/to/content.md For complete details including examples and best practices, see the [Source section in DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md#source). +### Excluding Internal Flags from Documentation Audits + +When documenting CLI commands, you may encounter internal flags or variable names from the source code that aren't intended for end-user documentation. +Use structured HTML comments to mark these flags as excluded from documentation audits. + +#### Standard exclude comment format + +Place the comment immediately before the **Options** section in CLI reference documentation: + +```markdown +## Options + + + +| Option | Description | +``` + +#### When to exclude flags + +Exclude flags and options that are: + +- **Internal variable names**: Source code argument names that aren't exposed as CLI flags +- **Hidden test flags**: Development or testing flags not meant for production use +- **Deprecated aliases**: Old flag names that are maintained for backward compatibility but shouldn't be documented +- **Implementation details**: Flags that expose internal implementation details + +#### Examples + +**Example 1: Internal variable name** + +```markdown +## Options + + +``` + +**Example 2: Multiple exclusions** + +```markdown +## Options + + +``` + +**Example 3: Hidden test flags** + +```markdown +## Options + + +``` + +#### Audit tool behavior + +Documentation audit tools should: + +1. Parse HTML comments with the `docs:exclude` identifier +2. Extract flag names and exclusion reasons using the pattern: `--flag-name: reason` +3. Skip reporting "missing documentation" for excluded flags +4. Support both single-line and multi-line exclusion lists + ### Common Shortcodes Reference diff --git a/content/influxdb3/core/reference/cli/influxdb3/serve.md b/content/influxdb3/core/reference/cli/influxdb3/serve.md index e3a6403b6..35fdd5835 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/core/reference/cli/influxdb3/serve.md @@ -42,6 +42,11 @@ influxdb3 serve [OPTIONS] ## Options + + | Option | | Description | | :--------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | | {{< req "\*" >}} | `--node-id` | _See [configuration options](/influxdb3/core/reference/config-options/#node-id)_ | diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md index f56a52695..f920b8253 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md @@ -43,6 +43,11 @@ influxdb3 serve [OPTIONS] ## Options + + | Option | | Description | | :--------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | | `--admin-token-recovery-http-bind` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-recovery-http-bind)_ | diff --git a/content/shared/influxdb3-cli/config-options.md b/content/shared/influxdb3-cli/config-options.md index be27b83f4..2104c636e 100644 --- a/content/shared/influxdb3-cli/config-options.md +++ b/content/shared/influxdb3-cli/config-options.md @@ -997,16 +997,17 @@ Specifies the maximum number of messages sent to a Jaeger service per second. - [datafusion-max-parquet-fanout](#datafusion-max-parquet-fanout) - [datafusion-use-cached-parquet-loader](#datafusion-use-cached-parquet-loader) - [datafusion-config](#datafusion-config) - + + #### datafusion-num-threads diff --git a/content/shared/influxdb3-cli/create/database.md b/content/shared/influxdb3-cli/create/database.md index 82378dd33..73147f5cc 100644 --- a/content/shared/influxdb3-cli/create/database.md +++ b/content/shared/influxdb3-cli/create/database.md @@ -19,6 +19,10 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme ## Options + + | Option | | Description | | :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | diff --git a/content/shared/influxdb3-cli/create/table.md b/content/shared/influxdb3-cli/create/table.md index 79c4e9ce9..5d72600b5 100644 --- a/content/shared/influxdb3-cli/create/table.md +++ b/content/shared/influxdb3-cli/create/table.md @@ -23,6 +23,9 @@ influxdb3 create table [OPTIONS] \ - **TABLE_NAME**: The name of the table to create. ## Options + {{% hide-in "enterprise" %}} | Option | | Description | diff --git a/content/shared/influxdb3-cli/create/trigger.md b/content/shared/influxdb3-cli/create/trigger.md index 1f1f8980e..4bfbd0d3c 100644 --- a/content/shared/influxdb3-cli/create/trigger.md +++ b/content/shared/influxdb3-cli/create/trigger.md @@ -21,6 +21,10 @@ influxdb3 create trigger [OPTIONS] \ ## Options + + | Option | | Description | | :----- | :------------------ | :------------------------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | diff --git a/content/shared/influxdb3-cli/delete/database.md b/content/shared/influxdb3-cli/delete/database.md index 14e1d4817..e9238402a 100644 --- a/content/shared/influxdb3-cli/delete/database.md +++ b/content/shared/influxdb3-cli/delete/database.md @@ -17,6 +17,10 @@ influxdb3 delete database [OPTIONS] ## Options + + | Option | | Description | | :----- | :------------ | :--------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | diff --git a/content/shared/influxdb3-cli/delete/table.md b/content/shared/influxdb3-cli/delete/table.md index c96178345..13d6de697 100644 --- a/content/shared/influxdb3-cli/delete/table.md +++ b/content/shared/influxdb3-cli/delete/table.md @@ -15,6 +15,10 @@ influxdb3 delete table [OPTIONS] --database ## Options + + | Option | | Description | | :----- | :------------ | :--------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | diff --git a/content/shared/influxdb3-cli/delete/trigger.md b/content/shared/influxdb3-cli/delete/trigger.md index ec72ff788..db8b94255 100644 --- a/content/shared/influxdb3-cli/delete/trigger.md +++ b/content/shared/influxdb3-cli/delete/trigger.md @@ -15,6 +15,10 @@ influxdb3 delete trigger [OPTIONS] --database ## Options + + | Option | | Description | | :----- | :----------- | :--------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | diff --git a/content/shared/influxdb3-cli/install/package.md b/content/shared/influxdb3-cli/install/package.md index ea30d7f3b..3c830ce62 100644 --- a/content/shared/influxdb3-cli/install/package.md +++ b/content/shared/influxdb3-cli/install/package.md @@ -13,6 +13,10 @@ influxdb3 install package [OPTIONS] [PACKAGES]... ## Options + + | Option | Description | Default | Environment Variable | | :---------------------------------------------- | :------------------------------------------------------------------ | :---------------------- | :-------------------------- | | `-H`, `--host ` | The host URL of the running {{< product-name >}} server | `http://127.0.0.1:8181` | `INFLUXDB3_HOST_URL` | diff --git a/lefthook.yml b/lefthook.yml index e910ae114..ee0410400 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -17,15 +17,17 @@ pre-commit: tags: lint glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md}" run: | - # Prepend /workdir/ to staged files since repository is mounted at /workdir in container - files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g') - docker compose run --rm --name remark-lint remark-lint $files --output --quiet || \ - { echo "⚠️ Remark found formatting issues in instruction files. Automatic formatting applied."; } + # Filter out content directory files, then prepend /workdir/ to each remaining file + files=$(echo '{staged_files}' | tr ' ' '\n' | grep -v '^content/' | sed 's|^|/workdir/|' | tr '\n' ' ' | sed 's/ $//') + if [ -n "$files" ]; then + docker compose run --rm --name remark-lint remark-lint $files --output --quiet || \ + { echo "⚠️ Remark found formatting issues in instruction files. Automatic formatting applied."; } + fi stage_fixed: true # Lint instruction and repository documentation files with generic Vale config lint-instructions: tags: lint - glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md,api-docs/README.md}" + glob: "{[A-Z]*.md,.github/**/*.md,.claude/**/*.md,api-docs/README.md}" run: '.ci/vale/vale.sh --config=.vale-instructions.ini --minAlertLevel=warning {staged_files}'