Skip to content

Conversation

bmorelli25
Copy link
Member

@bmorelli25 bmorelli25 commented Jan 10, 2025

Summary

  • Adds to migration, syntax, and contribution guides
  • Adds issue templates for bugs and enhancements
  • Adds scripts helpful for migration tasks

@@ -0,0 +1,59 @@
import re
Copy link
Member Author

@bmorelli25 bmorelli25 Jan 10, 2025

Choose a reason for hiding this comment

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

@elastic/docs-engineering I wonder if there's somewhere better to put these scripts instead of in the docs dir? A consideration is that some of these scripts output .md files that are included in the docs.

Copy link
Member

Choose a reason for hiding this comment

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

@bmorelli25 can you describe a bit what the intended use case is for these ?

Who runs them and when? is this a continuous thing?

Copy link
Member Author

@bmorelli25 bmorelli25 Jan 13, 2025

Choose a reason for hiding this comment

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

Good question. They're documented in the source files in this PR. But a brief summary is:

  1. CODEOWNER list for documentation freeze
    This script creates a list of repositories and the directories in those repositories that the @docs-freeze-team (just @KOTungseth) should be added as codeowner of. During a documentation freeze, the @docs-freeze-team must approve any pull requests that modify .asciidoc files before they can be merged. This prevents folks from merging docs changes during the freeze.

  2. Attribute converter
    This script converts the attributes in https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc to the supported yaml format for docs-builder.

1. HTML to Markdown Tab Converter
The tab converter script is used to convert HTML tabs into Markdown tabs within documentation files. The script scans through specified directories, finds all Markdown (.md) files, and replaces any HTML-based tab structures with their Markdown equivalents.
This is no longer necessary as @siamakp-elastic added this capability to the migration tool. I've removed this script from this PR.

Copy link
Member

Choose a reason for hiding this comment

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

  1. Is this something that needs to run continuously in the future or is this a one of thing?

  2. Same question really, but also:

    • Do we need all of these in the new architecture?
    • Rather then having these live in all of the isolated docset.yml files should docs-builder natively support them?

Copy link
Member Author

Choose a reason for hiding this comment

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

Is this something that needs to run continuously in the future or is this a one of thing?

Okay so after a meeting today, the CODEOWNER script won't be used so we can get rid of it. We will need to rerun the attribute converter eventually (Jan 29) but I can do that so there's no need to put it here (won't be used after that date). I'll remove both from this PR.

Do we need all of these in the new architecture?

All, no. Most, yes.

Rather then having these live in all of the isolated docset.yml files should docs-builder natively support them?

Yes. The more I play with this, the more a single yml file where these can be defined would be ideal.

@bmorelli25
Copy link
Member Author

The build is currently failing with

Error: Not linked in toc: migration/scripts/codeowner-gen/output.md

Opened a bug for this: #169

@bmorelli25 bmorelli25 requested a review from a team January 11, 2025 04:59
@bmorelli25 bmorelli25 marked this pull request as ready for review January 11, 2025 04:59
@bmorelli25
Copy link
Member Author

As discussed above, I removed the scripts from this PR. That also fixed the build error. I'm going to get this merged so that the GH pages is updated.

@bmorelli25 bmorelli25 merged commit 7cc289e into main Jan 14, 2025
3 checks passed
@bmorelli25 bmorelli25 deleted the add-to-guides branch January 14, 2025 00:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants