[docs] Migrate docs from AsciiDoc to Markdown

[colleenmcginnis]

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

[xrmx]

run docs-build

[colleenmcginnis]

@xrmx can you please review when you have a chance (preview)?

[xrmx]

I haven't gone through all but there a few things broken

[xrmx]

Rendering of this is broken

[colleenmcginnis]

I'll take a closer look at this today.

[colleenmcginnis]

elastic/docs-builder does not support CSS and JavaScript in Markdown, and there is no plan to support it in the future. I made some updates in e795df5. Take a look at the preview and let me know what you think about this approach.

[xrmx]

Something is wrong with rendering

[colleenmcginnis]

This is expected for now. It will be resolved when we're able to bundle pages from all repos together. elastic/docs-builder#621

[xrmx]

@colleenmcginnis What's the plan with the Pr after I approve? Do you plan to wait on the known issues to be resolved or not? I'm fine with rendering having issues but I'm worried to find other links that changed destination like the observability apm one.

[colleenmcginnis]

What's the plan with the Pr after I approve?

Not much will happen immediately. After this is merged, you'll continue to be able to see the preview at https://docs-v3-preview.elastic.dev/elastic/apm-agent-python/tree/main/reference/ (that link won't work until these files are on main). You'll also be able to start making edits directly to the Markdown files for new releases, etc.

In the next week or so we'll have the docs assembler ready to go, which will allow us to build these docs as a part of the larger Elastic docs. This will fix issues like elastic/docs-builder#621, and will allow you to see how APM Python agent docs fit into the larger information architecture.

Then, these docs will go live along with the Elastic Stack v9.0 release, and they will replace the current docs on elastic.co (the URLs will likely change, but we'll implement redirects for every current page). Previous versions will continue to be published using the AsciiDoc system, and the URLs will stay the same.

Do you plan to wait on the known issues to be resolved or not?

We don't have to wait on any known issues that are going to be fixed in docs-builder (like #2221 (comment)). If there are content-related problems, we should either (1) fix them before merging this PR or (2) open an issue to track any outstanding tasks so we can address them before the 9.0 release (example).

I'm fine with rendering having issues but I'm worried to find other links that changed destination like the observability apm one.

I can do a pass looking closely at each link later today.

[xrmx]

What's the plan with the Pr after I approve?

Not much will happen immediately. After this is merged, you'll continue to be able to see the preview at https://docs-v3-preview.elastic.dev/elastic/apm-agent-python/tree/main/reference/ (that link won't work until these files are on main). You'll also be able to start making edits directly to the Markdown files for new releases, etc.

In the next week or so we'll have the docs assembler ready to go, which will allow us to build these docs as a part of the larger Elastic docs. This will fix issues like elastic/docs-builder#621, and will allow you to see how APM Python agent docs fit into the larger information architecture.

Then, these docs will go live along with the Elastic Stack v9.0 release, and they will replace the current docs on elastic.co (the URLs will likely change, but we'll implement redirects for every current page). Previous versions will continue to be published using the AsciiDoc system, and the URLs will stay the same.

Yeah but at the moment everything we have in main is moved to the release branch, if this goes in that is not true anymore and I have to cherry-pick everything but the docs. So I would prefer to delay the merge as much as I can.

Do you plan to wait on the known issues to be resolved or not?

We don't have to wait on any known issues that are going to be fixed in docs-builder (like #2221 (comment)). If there are content-related problems, we should either (1) fix them before merging this PR or (2) open an issue to track any outstanding tasks so we can address them before the 9.0 release (example).

I'm fine with rendering having issues but I'm worried to find other links that changed destination like the observability apm one.

I can do a pass looking closely at each link later today.

That would be great, thanks!

[colleenmcginnis]

I can do a pass looking closely at each link later today.

That would be great, thanks!

I pushed a commit cleaning up some links (and other things) after looking at AsciiDoc and Markdown pages side by side.

Note: There are a couple links to new Markdown docs in other repos (like elastic/beats and elastic/ecs) that don't work yet because the equivalent of this PR in those repos also has not been merged into main yet. The build will error if those links don't work after the PRs have been merged in those repos (so we should be safe to merge here whenever).

Yeah but at the moment everything we have in main is moved to the release branch, if this goes in that is not true anymore and I have to cherry-pick everything but the docs. So I would prefer to delay the merge as much as I can.

Thanks for bringing this up. I chatted with @bmorelli25 about this today. We discussed implementing a solution similar to what we did for repos that did not have versioned docs (i.e. main === current) that might make the transition from AsciiDoc to Markdown a little less painful for the APM agent teams: elastic/docs#3185. With this solution, you'd be able to force push docs updates to 6.x without interrupting the AsciiDoc build while we wait for these docs to go live with the 9.0 release.

Take a look and let me know if you have any questions!