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 escapingpull/6573/head
Jason Stirnaman
GitHub
parent
d4eff43cf0
commit
0fcf2bdd31
|
|
@ -3,4 +3,7 @@
|
|||
**/.svn
|
||||
**/.hg
|
||||
**/node_modules
|
||||
assets/jsconfig.json
|
||||
assets/jsconfig.json
|
||||
|
||||
# Markdown files - Prettier insists on escaping common formatting
|
||||
**.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
|
||||
|
||||
<!--docs:exclude
|
||||
--internal-flag-name: reason for exclusion
|
||||
--another-internal-flag: reason for exclusion
|
||||
-->
|
||||
|
||||
| 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
|
||||
|
||||
<!--docs:exclude
|
||||
--database-name: internal variable, use positional <DATABASE_NAME>
|
||||
-->
|
||||
```
|
||||
|
||||
**Example 2: Multiple exclusions**
|
||||
|
||||
```markdown
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--table-name: internal variable, use positional <TABLE_NAME>
|
||||
--trigger-name: internal variable, use positional <TRIGGER_NAME>
|
||||
-->
|
||||
```
|
||||
|
||||
**Example 3: Hidden test flags**
|
||||
|
||||
```markdown
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--test-mode: hidden test flag, not for production use
|
||||
--serve-invocation-method: internal implementation detail
|
||||
-->
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
<!-- agent:instruct: essential -->
|
||||
### Common Shortcodes Reference
|
||||
|
||||
|
|
|
|||
|
|
@ -42,6 +42,11 @@ influxdb3 serve [OPTIONS]
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--serve-invocation-method: internal implementation detail
|
||||
--test-mode: hidden test flag, not for production use
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :--------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
|
||||
| {{< req "\*" >}} | `--node-id` | _See [configuration options](/influxdb3/core/reference/config-options/#node-id)_ |
|
||||
|
|
|
|||
|
|
@ -43,6 +43,11 @@ influxdb3 serve [OPTIONS]
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--serve-invocation-method: internal implementation detail
|
||||
--test-mode: hidden test flag, not for production use
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :--------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| | `--admin-token-recovery-http-bind` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-recovery-http-bind)_ |
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
<!-- DEV-ONLY FLAGS: DO NOT DOCUMENT IN PRODUCTION - TOKIO RUNTIME FLAGS
|
||||
- datafusion-runtime-type
|
||||
- datafusion-runtime-disable-lifo-slot
|
||||
- datafusion-runtime-event-interval
|
||||
- datafusion-runtime-global-queue-interval
|
||||
- datafusion-runtime-max-blocking-threads
|
||||
- datafusion-runtime-max-io-events-per-tick
|
||||
- datafusion-runtime-thread-keep-alive
|
||||
- datafusion-runtime-thread-priority
|
||||
END DEV-ONLY FLAGS -->
|
||||
|
||||
<!--docs:exclude
|
||||
--datafusion-runtime-type: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-disable-lifo-slot: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-event-interval: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-global-queue-interval: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-max-blocking-threads: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-max-io-events-per-tick: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-thread-keep-alive: development-only Tokio runtime configuration
|
||||
--datafusion-runtime-thread-priority: development-only Tokio runtime configuration
|
||||
-->
|
||||
|
||||
#### datafusion-num-threads
|
||||
|
||||
|
|
|
|||
|
|
@ -19,6 +19,10 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--database-name: internal variable, use positional <DATABASE_NAME>
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
||||
|
|
|
|||
|
|
@ -23,6 +23,9 @@ influxdb3 create table [OPTIONS] \
|
|||
- **TABLE_NAME**: The name of the table to create.
|
||||
|
||||
## Options
|
||||
<!--docs:exclude
|
||||
--table-name: internal variable, use positional <TABLE_NAME>
|
||||
-->
|
||||
|
||||
{{% hide-in "enterprise" %}}
|
||||
| Option | | Description |
|
||||
|
|
|
|||
|
|
@ -21,6 +21,10 @@ influxdb3 create trigger [OPTIONS] \
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--trigger-name: internal variable, use positional <TRIGGER_NAME>
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :----- | :------------------ | :------------------------------------------------------------------------------------------------------- |
|
||||
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
||||
|
|
|
|||
|
|
@ -17,6 +17,10 @@ influxdb3 delete database [OPTIONS] <DATABASE_NAME>
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--database-name: internal variable, use positional <DATABASE_NAME>
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :----- | :------------ | :--------------------------------------------------------------------------------------- |
|
||||
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
||||
|
|
|
|||
|
|
@ -15,6 +15,10 @@ influxdb3 delete table [OPTIONS] --database <DATABASE_NAME> <TABLE_NAME>
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--table-name: internal variable, use positional <TABLE_NAME>
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :----- | :------------ | :--------------------------------------------------------------------------------------- |
|
||||
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
||||
|
|
|
|||
|
|
@ -15,6 +15,10 @@ influxdb3 delete trigger [OPTIONS] --database <DATABASE_NAME> <TRIGGER_NAME>
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--trigger-name: internal variable, use positional <TRIGGER_NAME>
|
||||
-->
|
||||
|
||||
| Option | | Description |
|
||||
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
|
||||
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
||||
|
|
|
|||
|
|
@ -13,6 +13,10 @@ influxdb3 install package [OPTIONS] [PACKAGES]...
|
|||
|
||||
## Options
|
||||
|
||||
<!--docs:exclude
|
||||
--packages: internal variable, use positional [PACKAGES]...
|
||||
-->
|
||||
|
||||
| Option | Description | Default | Environment Variable |
|
||||
| :---------------------------------------------- | :------------------------------------------------------------------ | :---------------------- | :-------------------------- |
|
||||
| `-H`, `--host <HOST_URL>` | The host URL of the running {{< product-name >}} server | `http://127.0.0.1:8181` | `INFLUXDB3_HOST_URL` |
|
||||
|
|
|
|||
12
lefthook.yml
12
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}'
|
||||
|
|
|
|||
Loading…
Reference in New Issue