feat(docs): ensure docs using automation #161
Conversation
Summary of ChangesHello @b-long, I'm Gemini Code Assist1! 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 introduces an automated mechanism to extract code examples directly from MDX documentation files. By marking specific code blocks with special comments, a new set of scripts can parse the documentation and save these code snippets into a dedicated directory. This enhancement aims to improve the maintainability and reusability of code examples within the documentation, ensuring consistency and simplifying future updates. Highlights
Ignored Files
Using Gemini Code AssistThe 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
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 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
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces an automation script to extract code snippets from the documentation, which is a great step towards ensuring the examples are testable and up-to-date. My review focuses on the new scripts and the corresponding documentation changes. I've identified a few areas for improvement: there are some duplicated comment tags in getting-started/index.mdx that should be cleaned up, and the Node.js extraction script (extract-code-resources.js) could be made more efficient and robust with a single-pass approach and a more flexible regular expression for language detection. Overall, these are solid changes that will be even better with a few refinements.
| RESOURCES_TO_EXTRACT.forEach(resourceNum => { | ||
| const startMarker = `<!-- Code Resource ${resourceNum} Start -->`; | ||
| const endMarker = `<!-- Code Resource ${resourceNum} End -->`; | ||
|
|
||
| let extracting = false; | ||
| let codeLines = []; | ||
| let language = ''; | ||
| let inCodeBlock = false; | ||
|
|
||
| for (let i = 0; i < lines.length; i++) { | ||
| const line = lines[i]; | ||
| const trimmedLine = line.trim(); | ||
| // Remove blockquote markers for comparison | ||
| const cleanLine = line.replace(/^>\s*/, ''); | ||
|
|
||
| // Start extraction | ||
| if (cleanLine.includes(startMarker)) { | ||
| extracting = true; | ||
| continue; | ||
| } | ||
|
|
||
| // End extraction | ||
| if (cleanLine.includes(endMarker)) { | ||
| if (extracting && codeLines.length > 0) { | ||
| // Determine filename based on language | ||
| const ext = getFileExtension(language, resourceNum); | ||
| const filename = `code-resource-${resourceNum}${ext}`; | ||
| const filepath = path.join(OUTPUT_DIR, filename); | ||
|
|
||
| // Write the code to file | ||
| const code = codeLines.join('\n'); | ||
| fs.writeFileSync(filepath, code); | ||
| console.log(`✓ Extracted Resource ${resourceNum} -> ${filename} (${codeLines.length} lines)`); | ||
| extractedCount++; | ||
| } | ||
| extracting = false; | ||
| codeLines = []; | ||
| language = ''; | ||
| inCodeBlock = false; | ||
| break; | ||
| } | ||
|
|
||
| // Extract code content | ||
| if (extracting) { | ||
| // Detect start of code fence (handle blockquote markers) | ||
| const codeBlockMatch = cleanLine.trim().match(/^```(\w*)/); | ||
| if (codeBlockMatch) { | ||
| if (!inCodeBlock) { | ||
| // Starting code block | ||
| language = codeBlockMatch[1] || ''; | ||
| inCodeBlock = true; | ||
| } else { | ||
| // Ending code block | ||
| inCodeBlock = false; | ||
| } | ||
| continue; | ||
| } | ||
|
|
||
| // Add line if we're inside a code block (remove blockquote marker if present) | ||
| if (inCodeBlock) { | ||
| codeLines.push(cleanLine); | ||
| } | ||
| } | ||
| } | ||
| }); |
There was a problem hiding this comment.
The current implementation iterates over all lines of the MDX file for each resource to be extracted. This is inefficient as its time complexity is O(number_of_resources * number_of_lines). For better performance and scalability, consider refactoring this to a single pass over the file, which would have a complexity of O(number_of_lines).
A single-pass approach would involve iterating through the lines once and using a state machine to detect the start and end of any resource block.
| // Extract code content | ||
| if (extracting) { | ||
| // Detect start of code fence (handle blockquote markers) | ||
| const codeBlockMatch = cleanLine.trim().match(/^```(\w*)/); |
There was a problem hiding this comment.
The regex ^```(\w*) used to capture the language from a code fence is restrictive. The \w character class only includes alphanumeric characters and underscores ([a-zA-Z0-9_]). This will fail for language identifiers that contain hyphens, such as docker-compose. To make the script more robust, consider using a more permissive regex like ^```([\w-]*) to also allow hyphens.
| const codeBlockMatch = cleanLine.trim().match(/^```(\w*)/); | |
| const codeBlockMatch = cleanLine.trim().match(/^```([\w-]*)/); |
❌ Replaced by: