[docs] Migrate docs from AsciiDoc to Markdown

[colleenmcginnis]

DO NOT MERGE until preview has been reviewed

Migrate docs from AsciiDoc to Markdown. The preview can be built after #2805 is merged.

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

[pquentin]

Our Buildkite CI is currently broken, this is not related to this change. And Read the Docs was failing because it was using an image from the guide: ../guide/images/create-api-key.png. I fixed that in #2806 (fc0cc82).

[pquentin]

Thank you for your hard work!

Since we're planning to keep Read the Docs for API docs, I'm curious about the move from docs/guide to docs/reference which is a bit confusing in that regard. (Since I don't think of those docs as reference docs.)

[pquentin]

What is this file about? Will it need to be kept up-to-date?

[colleenmcginnis]

This file is used to configure the preview site for this repo. You can read more about it in the docs.

[pquentin]

The docs document the format, but don't answer my question about future maintenance. Will the list of subs need to change in the future? It currently contains hundreds of entries, copy/pasted across all those projects, I'm assuming.

(I'm just trying to understand, I'm not going to block this or anything.)

[marciw]

fair questions! The docs team is on the hook for subs maintenance -- we had similar substitutions in the old system (and i'm thinking/hoping you didn't hear much about those)

in general I'd say docset.yml is something the docs team can/should keep an eye on 👍

[pquentin]

What do those cross-links mean? Why APM Agent PHP?

[colleenmcginnis]

What do those cross-links mean?

cross_links defines all the other repos we link to in the docs in this repo. This is necessary for cross-repo link checking.

Why APM Agent PHP?

Good catch. I pushed an update in 3ab670e.

[marciw]

Since we're planning to keep Read the Docs for API docs, I'm curious about the move from docs/guide to docs/reference which is a bit confusing in that regard. (Since I don't think of those docs as reference docs.)

@pquentin Our new information architecture has these under /reference for now. We can iterate on the structure but would like to be able to go ahead and make this move in the meantime. Does that work for you?

[pquentin]

@marciw Sure. Why is this still a draft?

[marciw]

@marciw Sure. Why is this still a draft?

Wasn't sure it was ready but let's try it

[marciw]

@marciw Sure. Why is this still a draft?

@pquentin ah, sorry -- forgot we need to merge #2805 first. Both that one and this one are failing the Buildkite CI as you mentioned; any way to work around that?

[marciw]

preview https://docs-v3-preview.elastic.dev/elastic/elasticsearch-py/pull/2806/reference/

(the broken-looking nav entries at the bottom are a known issue that will go away when the docs are all built together)

[marciw]

@marciw Sure. Why is this still a draft?

@pquentin ah, sorry -- forgot we need to merge #2805 first. Both that one and this one are failing the Buildkite CI as you mentioned; any way to work around that?

looks like you can ignore this 🙂 in #2805 Miguel mentioned the tests will be fixed soon.