Generate the diagnostic pages from data files

[parlough]

• Updates dart run dash_site generate-diagnostics to generate a src/data/diagnostics.json file from data in the SDK. This file is not meant to be read or manually edited. It's mostly just a mechanism to cache the results calculated from the SDK data.
• Stops manually generating the individual diagnostic doc pages found at /tools/diagnostics/<diagnostic_name>. Instead use the data from the intermediate src/data/diagnostics.json file to generate each page from code. The content of the generated files remains the same with this PR.

These changes reduce site cloning and full build time, make updates easier to implement and review, and help avoid confusion about those files being the source of the docs.

Staged example page to show they remain functional and the same content wise: https://dart-dev--pr7061-misc-generate-diagnostic-pages-gr1n2k31.web.app/tools/diagnostics/abstract_super_member_reference

[gemini-code-assist]

Summary of Changes

Hello @parlough, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the site's diagnostic documentation system. It transitions from static Markdown files to a dynamic generation approach, where diagnostic details are sourced from a structured data file. This change aims to centralize diagnostic information, simplify updates, and enhance the overall efficiency of content management. The implementation involves new data parsing logic, updates to the page rendering pipeline, and the removal of redundant static content.

Highlights

• Diagnostic Page Migration: The pull request migrates diagnostic documentation pages from individual Markdown files to a data-driven generation system, improving maintainability and reducing site cloning time.
• New Data Model for Diagnostics: A new Dart model (diagnostic_model.dart) has been introduced to read and parse diagnostic information from a centralized JSON data file, defining the structure for DiagnosticInfo.
• Dynamic Page Generation Logic: The site's page generation (custom_pages.dart) now dynamically creates diagnostic pages based on the new DiagnosticInfo model, including handling redirects for previously named diagnostics and linking to related lint rules.
• Enhanced Tag Component: The Tag component in tags.dart has been updated to support an optional link attribute, allowing tags to be clickable and navigate to relevant pages.
• Removal of Static Markdown Files: Numerous individual diagnostic Markdown files (e.g., abi_specific_integer_invalid.md, abstract_field_initializer.md) have been removed, reflecting the successful transition to data-driven content.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a great refactoring that migrates the diagnostic documentation pages to be generated from a data file. This will improve site build times and make maintenance easier. The changes are well-structured, introducing a new model for diagnostic information and updating the page generation logic accordingly.

I've found one area for improvement in site/lib/src/pages/custom_pages.dart regarding the construction of the markdown content for diagnostic pages. The current implementation could lead to rendering "null" for diagnostics without documentation and might produce extra newlines. I've suggested a more robust way to build the content string that handles these cases gracefully.

Overall, this is a solid contribution.

[dart-github-bot]

Visit the preview URL for this PR (updated for commit 3936563):

https://dart-dev--pr7061-misc-generate-diagnostic-pages-gr1n2k31.web.app

[antfitch]

Love this! Let's look at the data serialization patterns we are using on the site and pick one to focus on moving forward. I'm specifically thinking about formats we are currently using (YML, JSON). We have a meeting coming up and that will be a good time for all of us to discuss.

[antfitch]

Let's choose a data serialization strategy for Dash sites before committing this.

[antfitch]

I'm on board! @ericwindmill have any change requests?