Skip to content

[docs] Migrate docs from AsciiDoc to Markdown#2451

Merged
colleenmcginnis merged 16 commits intoelastic:mainfrom
colleenmcginnis:migrate-docs
Mar 13, 2025
Merged

[docs] Migrate docs from AsciiDoc to Markdown#2451
colleenmcginnis merged 16 commits intoelastic:mainfrom
colleenmcginnis:migrate-docs

Conversation

@colleenmcginnis
Copy link
Copy Markdown
Contributor

@colleenmcginnis colleenmcginnis commented Feb 25, 2025

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

@colleenmcginnis colleenmcginnis added the DOCS Any issue related to ECS documentation label Feb 25, 2025
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Feb 25, 2025

Documentation changes preview: https://ecs_bk_2451.docs-preview.app.elstc.co/diff

@colleenmcginnis colleenmcginnis mentioned this pull request Mar 4, 2025
Merged
@mjwolf
Copy link
Copy Markdown
Contributor

mjwolf commented Mar 4, 2025

@colleenmcginnis There were some changes made to ECS after the docs freeze. Are the new docs generated from the latest main branch? Most of the changes are to the schema files, so I think docs should get the latest changes from automatic generation.

One other thing I saw is docs/release-notes/8.17.asciidoc is not deleted in this PR. It was added to main recently, so it should be deleted with the other asciidoc files.

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 4, 2025

Are the new docs generated from the latest main branch?

No. They were generated at the start of the docs freeze.

Most of the changes are to the schema files, so I think docs should get the latest changes from automatic generation.

Is the automatic generation still creating AsciiDoc files? If so, they will need to be updated to Markdown.

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 4, 2025 •
edited
Loading

Most of the changes are to the schema files, so I think docs should get the latest changes from automatic generation.

Is the automatic generation still creating AsciiDoc files? If so, they will need to be updated to Markdown.

I resolved the merge conflicts. Do these look like the only updates that would have been made? 5cb6754?file-filters%5B%5D=.md&show-deleted-files=true&show-viewed-files=true

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 4, 2025

@mdbirnstiehl this should fix the inbound link validation error: elastic/apm-agent-dotnet#2563

@colleenmcginnis colleenmcginnis marked this pull request as ready for review March 4, 2025 21:46
@colleenmcginnis colleenmcginnis requested a review from a team as a code owner March 4, 2025 21:46
@colleenmcginnis colleenmcginnis requested a review from mjwolf March 5, 2025 15:34
@mdbirnstiehl
Copy link
Copy Markdown
Member

mdbirnstiehl commented Mar 6, 2025

@mjwolf Could you help us out here on the test failing. Also, do you know if there were any additional changes made other than the ones mentioned by @colleenmcginnis?

@mjwolf
Copy link
Copy Markdown
Contributor

mjwolf commented Mar 10, 2025

Hi @colleenmcginnis, @mdbirnstiehl, there will need to be an update to the ECS generators to create markdown files from the schema files. Right now it's being done in this python script to generate asciidoc: https://github.com/elastic/ecs/blob/main/scripts/generators/asciidoc_fields.py I don't see an equivilent in this PR to create markdown. This might be tricky to do, so I can work on it.

It also looks like the make docs command is working from asciidoc: https://github.com/colleenmcginnis/ecs/blob/migrate-docs/Makefile#L45-L50. I don't know much about builders in the docs repo or what that command is actually doing. Could you look at this and see if it needs to be updated.

@bmorelli25
Update makefile to use docs-builder
5a6d593 
Signed-off-by: bmorelli25 <brandon.morelli@elastic.co>
@bmorelli25
Copy link
Copy Markdown
Member

bmorelli25 commented Mar 10, 2025

Right now it's being done in this python script to generate asciidoc: https://github.com/elastic/ecs/blob/main/scripts/generators/asciidoc_fields.py I don't see an equivilent in this PR to create markdown. This might be tricky to do, so I can work on it.

Thank you, @mjwolf!

It also looks like the make docs command is working from asciidoc: https://github.com/colleenmcginnis/ecs/blob/migrate-docs/Makefile#L45-L50. I don't know much about builders in the docs repo or what that command is actually doing. Could you look at this and see if it needs to be updated.

Ah, yes, this does need to be updated. We are using a new documentation publication tool. I pushed 5a6d593 which updates the script to use this new docs-builder tool. Tested on macOS and it works. Not sure if this is an acceptable way to determine OS though.

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 11, 2025

👋 @mjwolf I chatted with @lcawl about the fieldsets pages that include tab sets. She's going to push some changes to this PR that use a simpler pattern to distinguish between beta and GA fields. Hopefully that will be easier to add to the automation updates.

@lcawl
Copy link
Copy Markdown
Member

lcawl commented Mar 11, 2025

... She's going to push some changes to this PR that use a simpler pattern to distinguish between beta and GA fields.

Done in a3a944e, ff361a7, and cb43056

mjwolf and others added 2 commits March 13, 2025 12:21
@mjwolf
[work in progress] Migrate docs md generator (#1)
e296a06 
* Update docs generator to markdown

* generate fieldset docs

* Update fieldset formatting

* Update fieldset formatting

* Change otel dir

* Update more formatting

* Include usage in docs

* Update otel docs generation

* update template files to fix images, links, tables

* commit updated markdown files

* fix extra pipe

* fix otel docs formatting

* Update fieldset

* update more formatting

* Update unit tests

* More formatting fixes

* fix usage section in fieldset template

* update nested fieldset

* fix syntax issues causing build errors

* only build ext link if it's needed

* commit generated markdown files

---------

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>
@mjwolf
Fix lint errors
3d57055
mjwolf
mjwolf approved these changes Mar 13, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@mjwolf mjwolf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This now has the generator scripts updated to create markdown docs; the docs will be kept up-to-date with future schema changes.

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 13, 2025

@mjwolf is it ok if I update these two files to change the link syntax used from AsciiDoc to Markdown?

@colleenmcginnis
Copy link
Copy Markdown
Contributor Author

colleenmcginnis commented Mar 13, 2025

@mjwolf is it ok if I update these two files to change the link syntax used from AsciiDoc to Markdown? (#2451 (comment))

Per Slack, we will do this in a follow-up PR.

@colleenmcginnis colleenmcginnis merged commit db9a948 into elastic:main Mar 13, 2025
4 checks passed
@colleenmcginnis colleenmcginnis deleted the migrate-docs branch March 13, 2025 21:06
@colleenmcginnis colleenmcginnis mentioned this pull request Mar 13, 2025
Closed
48 tasks
mjwolf added a commit to mjwolf/ecs that referenced this pull request Apr 22, 2025
@mdbirnstiehl @bmorelli25
@lcawl @mjwolf
[docs] Migrate docs from AsciiDoc to Markdown (elastic#2451)
eb3c003 
* delete asciidoc files

* add migrated files

* clean up cross-repo links

* add missing ecs and otel pages

* add mapped_pages

* fix external links

* Update makefile to use docs-builder

Signed-off-by: bmorelli25 <brandon.morelli@elastic.co>

* Remove tabs from ecs-code_signature.md

* Remove tabs from ecs-device.md

* Remove remaining beta tabs

* [work in progress] Migrate docs md generator (#1)

* Update docs generator to markdown

* generate fieldset docs

* Update fieldset formatting

* Update fieldset formatting

* Change otel dir

* Update more formatting

* Include usage in docs

* Update otel docs generation

* update template files to fix images, links, tables

* commit updated markdown files

* fix extra pipe

* fix otel docs formatting

* Update fieldset

* update more formatting

* Update unit tests

* More formatting fixes

* fix usage section in fieldset template

* update nested fieldset

* fix syntax issues causing build errors

* only build ext link if it's needed

* commit generated markdown files

---------

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

* Fix lint errors

* clean up spacing

* commit changes to layout

---------

Signed-off-by: bmorelli25 <brandon.morelli@elastic.co>
Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com>
Co-authored-by: bmorelli25 <brandon.morelli@elastic.co>
Co-authored-by: lcawl <lcawley@elastic.co>
Co-authored-by: Michael Wolf <michael.wolf@elastic.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mjwolf mjwolf mjwolf approved these changes

@mdbirnstiehl mdbirnstiehl Awaiting requested review from mdbirnstiehl

Assignees

No one assigned

Labels

DOCS Any issue related to ECS documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@colleenmcginnis @mjwolf @mdbirnstiehl @bmorelli25 @lcawl