Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

move codesnippets to md files #571

Open
4 tasks done
userquin opened this issue Mar 4, 2024 · 3 comments · May be fixed by #575
Open
4 tasks done

move codesnippets to md files #571

userquin opened this issue Mar 4, 2024 · 3 comments · May be fixed by #575
Assignees
Labels
docs Improvements or additions to documentation help wanted Extra attention is needed p2-nice-to-have Not breaking anything but nice to have (priority)

Comments

@userquin
Copy link
Member

userquin commented Mar 4, 2024

Description

To avoid duplication and errors, all code snippets should be moved to a new md file, this way we only need to update an md file.

Suggested solution

Read the description

Alternative

No response

Additional context

No response

Validations

@userquin userquin self-assigned this Mar 4, 2024
@andretchen0
Copy link
Contributor

andretchen0 commented Mar 4, 2024

Maybe helpful/relevant to this issue:

For Cientos, for on-screen demos with snippets, we've been including demos then showing the demo's own code using VitePress' built-in include syntax.

Live docs page

https://cientos.tresjs.org/guide/staging/sky.html

Code for docs page

# Sky

<DocsDemo>
  <SkyDemo />
</DocsDemo>

`<Sky />` is a wrapper for the [Three.js `Sky` add-on](https://threejs.org/examples/?q=sky#webgl_shaders_sky).

## Usage

<<< @/.vitepress/theme/components/SkyDemo.vue{3,9}

## Props

<CientosPropsTable component-path="src/core/staging/Sky.vue" />

Link to GH

When writing docs, having snippets that are runnable and running on the page has kept me from introducing bugs in the demo code a few times.

It also has a positive effect, imho, of forcing me to make a minimum runnable example, which is then directly runnable by users; they don't have to figure out, e.g., "Where do I paste this?"

@userquin
Copy link
Member Author

userquin commented Mar 4, 2024

I'll include only code snippets, we've 3 languages and 2 more comming, we need to update only the example once avoiding to update every code snippet in every localised page.

About running examples, we should do it also once.

@userquin userquin linked a pull request Mar 4, 2024 that will close this issue
@andretchen0
Copy link
Contributor

@userquin

Sounds good. Good luck!

@alvarosabu alvarosabu added docs Improvements or additions to documentation p2-nice-to-have Not breaking anything but nice to have (priority) help wanted Extra attention is needed and removed enhancement labels Mar 28, 2024
@alvarosabu alvarosabu moved this to Todo in Team Board Aug 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to documentation help wanted Extra attention is needed p2-nice-to-have Not breaking anything but nice to have (priority)
Projects
Status: Todo
Development

Successfully merging a pull request may close this issue.

3 participants