[docs] Migrate docs from AsciiDoc to Markdown

[eedugon]

Migrates docs from AsciiDoc to Markdown

Preview available at https://docs-v3-preview.elastic.dev/elastic/cloud-on-k8s/pull/8496/reference

This PR should substitute #8494 created by @colleenmcginnis (I didn't have permissions to merge the latest changes in main, and I might need to add a few extra changes to the content).

This PR:

• Deletes all static .asciidoc files of the previous documentation system (this files can still be updated on the 2.x / 1.x branches).
• Places new markdown content for reference, release notes, known issues, deprecations and breaking changes sections. This content will eventually be replaced by automatic generated content.

[eedugon]

This PR cannot be merged until the CI jobs are adjusted (https://buildkite.com/elastic/cloud-on-k8s-operator/builds/10389#019547bc-f8e5-46dd-93a0-1ae3a0f48d99).

Based on @pebrc comments, the steps to take are:

1. disable the master/main docs build in favour of the new CI checks merged on [docs] Add the new docs CI checks #8493
2. adjust the repository tooling (which will otherwise fail all builds)
3. merge this PR.

[pebrc]

@eedugon can we get this into a mergeable state? As we are preparing for the 3.0 release and we need to make docs changes it would be good to have the docs as close as possible to the final file layout to avoid double effort on our end maintaining changes in two repos.

[eedugon]

on it @pebrc !
And yes, much better to merge all this in main before creating a 3.0 branch.

[eedugon]

@pebrc : FYI, while fixing the conflicts:

• File advanced-topics/service-meshes.asciidoc was modified in main branch and we are deleting it in this PR.
• File release-notes/2.16.0.asciidoc was modified in main branch and we are deleting it in this PR.

The previous files should be updated only in branches different than main or 3.0 (whenever 3.0 branch exists).
The release notes should be markdown (this PR includes a draft).

[eedugon]

@pebrc , the build is failing because of the links auto-generated in third-party-dependencies.md. The docs-builder tool doesn't like them.

The new links look like:

| [https://dario.cat/mergo]($$dario.cat/mergo$$) | v1.0.1 | BSD-3-Clause |
| [https://github.com/Masterminds/sprig]($$github.com/Masterminds/sprig/v3$$) | v3.3.0 | MIT |
| [https://github.com/blang/semver]($$github.com/blang/semver/v4$$) | v4.0.0 | MIT |
| [https://github.com/davecgh/go-spew]($$github.com/davecgh/go-spew$$) | v1.1.2-0.20180830191138-d8f796af33cc | ISC |
| [https://github.com/elastic/go-ucfg]($$github.com/elastic/go-ucfg$$) | v0.8.8 | Apache-2.0 |
| [https://github.com/ghodss/yaml]($$github.com/ghodss/yaml$$) | v1.0.0 | MIT |

And in the static content we had provided they looked like:

| [dario.cat/mergo](https://dario.cat/mergo) | v1.0.1 | BSD-3-Clause |
| [github.com/Masterminds/sprig/v3](https://github.com/Masterminds/sprig) | v3.3.0 | MIT |
| [github.com/blang/semver/v4](https://github.com/blang/semver) | v4.0.0 | MIT |
| [github.com/davecgh/go-spew](https://github.com/davecgh/go-spew) | v1.1.2-0.20180830191138-d8f796af33cc | ISC |
| [github.com/elastic/go-ucfg](https://github.com/elastic/go-ucfg) | v0.8.8 | Apache-2.0 |
| [github.com/ghodss/yaml](https://github.com/ghodss/yaml) | v1.0.0 | MIT |
| [github.com/gkampitakis/go-snaps](https://github.com/gkampitakis/go-snaps) | v0.5.8 | MIT |

I'm sorry I didn't get this in your previous PR. Would you please fix the auto-generated file in main?

As an extra issue, the markdown comments in the new Docs V3 system should be made with % (details here ), so the following won't work as a comment:

<!--- Generated documentation. Please do not edit. --->

It should be:

% Generated documentation. Please do not edit.

[pebrc]

@pebrc : FYI, while fixing the conflicts:

* File `advanced-topics/service-meshes.asciidoc` was modified in main branch and we are deleting it in this PR.

I can open a PR against the new docs repo for that.

* File `release-notes/2.16.0.asciidoc` was modified in main branch and we are deleting it in this PR.

We can ignore this change as it was backported to the 2.16 branch already.

[pebrc]

You are running into another problem with the build.

cloud-on-k8s/Makefile

Lines 499 to 507 in 95acd68

	# Check if the predicate names in upgrade_predicates.go, are equal to the predicate names
	# defined in the user documentation in orchestration.asciidoc.
	check-predicates: CODE = pkg/controller/elasticsearch/driver/upgrade_predicates.go
	check-predicates: DOC = docs/orchestrating-elastic-stack-applications/elasticsearch/orchestration.asciidoc
	check-predicates: PREDICATE_PATTERN = [a-z]*_[A-Za-z_]*
	check-predicates:
	@ diff \
	<(grep "name:" "$(CODE)" | grep -o "$(PREDICATE_PATTERN)" ) \
	<(grep '\*\* [a-z]' "$(DOC)" | grep -o "$(PREDICATE_PATTERN)" )

This is some code that we added to verify that the documentation was always up to date compared to the code. Unfortunately with the docs moving out of this repo this check won't work anymore and you will have to either remove it or move the documentation of the update predicates back into this repo as reference documenation.

[eedugon]

working on this, @pebrc, thanks for flagging it.

[eedugon]

@pebrc : This PR is mergeable now. Feel free to review it.

We have added to docs/reference a new doc with the info about upgrade predicates and the example use case, and updated the Makefile to perform the verification with the new .md file.

In the main nodes orchestration doc we have updated the content with just an introduction and link to reference in the Advanced control during rolling upgrades section.

Let us know your thoughts. We can also change the title of the new reference doc at a later stage.