forked from dagster-io/dagster
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs/code snippet tag2 (dagster-io#23117)
## Summary & Motivation After ruling out the "Client fetches code snippets from github" approach, I ended up reimplementing it to be handled on the server. I've also updated the github docs build action to watch the examples folder as a location for updates and copy the content of the examples into the next site when it is time to update. ### What was added - A new next API route (`/api/code-snippet`) to handle fetching and processing code snippets. - A React component (CodeSnippet) to render these snippets in the documentation. - Markdoc tag declaration for easy use of the CodeSnippet component in markdown files. - Environment-aware file path handling for both local development and production. - Updates to the GitHub Actions workflow to copy snippet files to the correct location during deployment. - Fixes to an animation bug that emerged during the work. ## How I Tested These Changes ### Local Development: - I tested the API route with various parameter combinations to ensure correct snippet extraction. - Verified that the React component correctly renders snippets fetched from the API. - Confirmed that the environment-aware path handling works correctly in the local development environment. ### Markdoc Integration: - Created sample Markdoc files with various CodeSnippet tag usages to ensure proper rendering. - Tested different parameter combinations within Markdoc tags. ### Production Simulation: - Simulated a production environment locally to verify that file paths are correctly resolved. - Tested the GitHub Actions workflow in a feature branch to ensure snippet files are correctly copied during deployment. ### Edge Cases - Tested error handling for non-existent files, invalid parameters, and network issues. - Verified behavior with empty snippets, very large snippets, and snippets with special characters. ### Performance - Conducted basic performance tests to ensure that snippet loading doesn't significantly impact page load times.
- Loading branch information
Showing
7 changed files
with
379 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| import React, { useState, useEffect } from 'react'; | ||
| import { Fence } from './FencedCodeBlock'; | ||
|
|
||
| interface CodeSnippetProps { | ||
| file: string; | ||
| lang: string; | ||
| lines?: string; | ||
| startafter?: string; | ||
| endbefore?: string; | ||
| dedent?: number; | ||
| trim?: boolean; | ||
| } | ||
|
|
||
| const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL || ''; | ||
|
|
||
| const fetchSnippet = async (params: CodeSnippetProps) => { | ||
| const queryParams = new URLSearchParams({ | ||
| file: params.file, | ||
| ...(params.lines && { lines: params.lines }), | ||
| ...(params.startafter && { startafter: params.startafter }), | ||
| ...(params.endbefore && { endbefore: params.endbefore }), | ||
| ...(params.dedent && { dedent: params.dedent.toString() }), | ||
| ...(params.trim !== undefined && { trim: params.trim.toString() }), | ||
| }); | ||
|
|
||
| const response = await fetch(`${API_BASE_URL}/api/code-snippet?${queryParams}`); | ||
| if (!response.ok) { | ||
| throw new Error('Failed to fetch snippet'); | ||
| } | ||
| return response.text(); | ||
| }; | ||
|
|
||
| export const CodeSnippet: React.FC<CodeSnippetProps> = (props) => { | ||
| const [snippet, setSnippet] = useState<string>(''); | ||
| const [isLoading, setIsLoading] = useState<boolean>(true); | ||
| const [error, setError] = useState<string | null>(null); | ||
|
|
||
| useEffect(() => { | ||
| const fetchData = async () => { | ||
| try { | ||
| setIsLoading(true); | ||
| const data = await fetchSnippet(props); | ||
| setSnippet(data); | ||
| } catch (err) { | ||
| setError(err.message); | ||
| } finally { | ||
| setIsLoading(false); | ||
| } | ||
| }; | ||
|
|
||
| fetchData(); | ||
| }, [props]); | ||
|
|
||
| if (isLoading) return <div>Loading snippet...</div>; | ||
| if (error) return <div>Error: {error}</div>; | ||
|
|
||
| return <Fence data-language={props.lang}>{snippet}</Fence>; | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.