Split example file docblock and code when generating web examples markdown #18191
Conversation
alice-i-cecile
added
C-Examples
alice-i-cecile
added
S-Ready-For-Final-Review
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
There was a problem hiding this comment.
The rust specification does allow for inner doc comments anywhere in the file, but that seems like a case that's not super worth putting a ton of time into handling. This does appear to be a clear improvement over the alternative. Personally I don't mind reading the inner doc comments in the code block, but see little risk in this approach.
edit: didn't realize this was already in the merge queue. Well... "and my axe!" I suppose.
Here we have control of where the doc comment we want is, so not a problem 🙂 |
…kdown (#18191) # Objective Separate example explanation (file docblock) and the code so they can be layout differently in the website and we can give a higher importance to the explanation on the [website search tool](bevyengine/bevy-website#1935). This would also allow us to improve the examples so they become even more like a cookbook. ## Solution Update the `example-showcase` tool to extract the example file docblock and write it as the example markdown content. This allows us to access the explanation via `page.content` in Zola. ## Testing I've checked that the output is correct after running the tool and it doesn't throw any error. I've also validated that the approach will work on the website. ## Showcase This is a quick and dirty example of what we could do in the web examples after the change. When we implement the real thing we can put the explanation on a sidebar or explore other layout options. <img width="1362" alt="image" src="https://github.com/user-attachments/assets/6738542e-31c3-41cd-972a-7fa2e942e85d" />
5 participants
Objective
Separate example explanation (file docblock) and the code so they can be layout differently in the website and we can give a higher importance to the explanation on the website search tool. This would also allow us to improve the examples so they become even more like a cookbook.
Solution
Update the
example-showcasetool to extract the example file docblock and write it as the example markdown content. This allows us to access the explanation viapage.contentin Zola.Testing
I've checked that the output is correct after running the tool and it doesn't throw any error. I've also validated that the approach will work on the website.
Showcase
This is a quick and dirty example of what we could do in the web examples after the change. When we implement the real thing we can put the explanation on a sidebar or explore other layout options.