[Docs test] Config settings mock-up

[kilfoyle]

Summary

Please don't merge!

This is a mock-up of how a list of Kibana settings can be rendered in Asciidoc from a YAML source file (kibana-config-settings.yml) that contains a list of all public Kibana configuration settings and their properties.

1. kibana-config-settings.yml → Perl script: perl parse-settings.pl → kibana-config-settings.asciidoc (contains Asciidoc-formatted settings snippets).

2. alert-action-settings-new.asciidoc (replacing the original alert-action-settings.asciidoc content with simple include statements) pulls in those snippets, and from that source file we generate the HTML public docs.

Note: If you want to run the Perl script you need to update the variables at lines 18 and 19 to your local path. For example: my $sourcedir = '/Users/kilfoyle/repos/kibana/docs/settings-gen/source'; my $asciidocdir = '/Users/kilfoyle/repos/kibana/docs/settings-gen/source/';

Rel: https://github.com/elastic/docs-projects/issues/239

---

How these files fit together

[github-actions[bot]]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[obltmachine]

:robot: GitHub comments

Expand to view the GitHub comments

Just comment with:

• /oblt-deploy : Deploy a Kibana instance using the Observability test environments.
• run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)

[elasticmachine]

Pinging @elastic/kibana-docs (Team:Docs)

[kilfoyle]

@elastic/kibana-operations, @kobelb Apologies for the ping but I'd really appreciate if someone can help with this PR and Luke's questions above.

[jbudz]

Most important thing to review: are we generally comfortable with the yml schema design here? Because this will dictate the authoring experience for yml config docs in the future

Seems fine, it covers all the needs of existing settings and we'll be in a position to adjust if needed

Is the current directory the right location for the conversion script or does it belong in a separate package? (Currently the script relies on living in the directory with the files it is running against).

We don't run CI on changes only in the docs folder but if validation is left to Kibana CI we'll want to make an adjustment to https://github.com/elastic/kibana/blob/main/.buildkite/pull_requests.json#L24.

If it remains static I don't see issues. If not, it could be difficult to maintain across all repositories with docs and all branches. It does need to be accessible locally by contributors in some form and this is easiest in that regard.

Is the current directory the right location for the generated docs? Due to the way docs are released, we need the generated docs to be committed to the repo

:+1:

What would the level of effort be to, as a follow-up task, automate the running of this script in CI and auto-commiting the output on PRs?

Low, except we shut off Kibana CI on old branches. We would have to a create a docs only check, similar to buildkite/docs-build-pr. Preferably the check could be baked into that one.

[kilfoyle]

@kobelb, thanks very much for the excellent suggestions!

Two small corrections.

Both are fixed.

Having the example in a separate file is cumbersome. Is it possible for these to be inline and use the multi-line YAML strings?

Indeed, it's a lot less cumbersome having the examples included in the YAML rather than in a separate file, so I've made that change.

Rendering each setting in a collapsible section made consuming these docs hard. However, I'm quite adjusted to the old format, so take this with a grain of salt.

I was thinking that the collapsible sections looked tidier, but on further thought I agree that the usability is much better without them. I've removed them.

If you have other suggestions to improve the formatting I'm happy to add them in. Preview page is here.

[kilfoyle]

@jbudz and @lukeelmers thanks a lot for your feedback on this PR!

I've addressed the suggestions so far. Are there any changes you'd like or do you think this is ready to merge?

[lukeelmers]

No concerns on my end as long as we get a ✅ from @jbudz or someone on the ops team.

[kilfoyle]

Based on feedback I've made a few changes:

• Each setting description is now a whitespace-preserving multiline string, rather than an array of strings (it's much cleaner this way).
• Each setting now has a required "datatype" field that can be one of string/bool/int/float/enum. When enum is selected, the list of supported options should be defined using the options keys.
• Tidied up the readme.

[kilfoyle]

There's an error to do with the codeowners file that I'm not sure how to fix:

Unknown owner on line 3325: make sure the team @elastic/obs-ux-onboarding-team exists, is publicly visible, and has write access to the repository

That @elastic/obs-ux-onboarding-team team is also included in the codeowners file on main. So maybe the error can be ignored?

[jbudz]

Where did this land on automation? Are we leaving it as a manual process for now?

[elasticmachine]

:green_heart: Build Succeeded

• Buildkite Build
• Commit: 8d81873f2cf0f2b5ce53c070414e2bd8cfaa762b

Metrics [docs]

✅ unchanged

History

• :green_heart: Build #262087 succeeded 519cdf94da82728a7b81b2227ef1ae621044d049
• :green_heart: Build #261610 succeeded a4cbb70a2debfa0bf9764f072c02d0813b5ede48
• :green_heart: Build #260879 succeeded 3008521b4ed2154312bd528e5eb38af4637eac63
• :green_heart: Build #260073 succeeded 72135bcc8e23ec23dccf31d6347737be29ffc479
• :green_heart: Build #256673 succeeded 035e4598d4f7f11020a244c9c0a8e799494792a6
• :green_heart: Build #254018 succeeded fd7d0e2518ac07c56ce50a0d6270cdbe19035718

[kilfoyle]

Where did this land on automation? Are we leaving it as a manual process for now?

@jbudz Yes, it will be a manual process for now. Thanks to Add initial support for structured settings references (yaml), in the upcoming new Docs V3, processing of the yaml settings files will be handled automatically as part of the docs build (@Mpdreamz please correct me if that's not right).

For sure, the Perl script added in this PR will not need to be run automatically, and it will exist just temporarily until we arrive at the new and better docs system.