[Docs] Update "Alert and action settings" docs to be generated from YAML source

[kilfoyle]

This PR:

• Updates the Kibana Alert and action settings page to be based off of a YAML source file (/docs/settings-gen/source/kibana-alert-action-settings.yml) that is manually converted to Asciidoc format (kibana-alert-action-settings.asciidoc) by means of a Perl script (docs/settings-gen/parse-settings.pl). A preview of the new, generated page is here.
• Adds the docs/settings-gen/parse-settings.pl script which does the YAML → Asciidoc conversion.

All new files are added to the /docs/source-gen folder.

This is a trial run updating only one page of settings in the docs. Later, in separate PRs, we plan to convert other pages. After all Kibana settings pages have been converted, we would ask that the Perl script be run automatically as part of the CI whenever the YAML files in /docs/source-gen are added or updated.

Notes:

• The Docs team is happy to own and maintain the Perl script (sorry to use Perl - it's the only scripting language that I know).
• In time we also plan to convert all of these files from Asciidoc to Markdown.
• When we eventually/hopefully get the rest of the Kibana settings files converted, we will announce the settings doc process to the Kibana team by email and/or in the Kibana newsletter.

Big thanks to the amazing @lukeelmers and @KOTungseth for guiding this!

---

Why are we doing this? We aim to:

• Create a more consistent appearance for settings across all of the docs.
• Make it easier for people to contribute, since all Asciidoc/Markdown formatting is handled by a script.
• Make it more apparent which settings may be missing info, such as the default values, available options, etc.

---

P.S. I haven't worked in the Kibana repo very much and would appreciate any help navigating the CI checks.

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

[github-actions]

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]

🤖 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!)

[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]

💚 Build Succeeded

• Buildkite Build
• Commit: 8d81873

Metrics [docs]

✅ unchanged

History

• 💚 Build #262087 succeeded 519cdf9
• 💚 Build #261610 succeeded a4cbb70
• 💚 Build #260879 succeeded 3008521
• 💚 Build #260073 succeeded 72135bc
• 💚 Build #256673 succeeded 035e459
• 💚 Build #254018 succeeded fd7d0e2

[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.