bevyengine / bevyengine/bevy-website
Add a way to draw charts, graphs and diagrams from markdown / code / text
- Dominant language
- JavaScript
- Stars
- 249
- Forks
- 450
- Avg merge
- 16h 20m
- Merged PRs (30d)
- 6
Description
## Motivation
- A lot of the learning-material in the Bevy-book can be improved by displaying graphs or diagrams as shown here: https://github.com/bevyengine/bevy-website/pull/290#issuecomment-1076737664
- Nearly all release-notes contain some form of charts, and will likely continue to do so in the future. Improving the process of creating these charts could take workload off of core maintainers and democratize the process
- **Hypothesis:** Graphs and diagrams that are drawn from text or code is easier to maintain by a team compared to static images generated by a user
- I initially thought adding mermaid support would be enough (#377) but after playing with it some it seems to not fully suitable
- See the following comment-chain for details: https://github.com/bevyengine/bevy-website/pull/377#issuecomment-1140412302
- TLDR; mermaid is not really set up for ease of customization
## Types of diagrams we should consider supporting
I've focused on diagrams already in use or known to wanted in the near future
Type | Examples | Notes
|---|---|---|
Gantt Diagram | [1](https://bevyengine.org/news/bevy-0-6/#pipelined-rendering-extract-prepare-queue-render) | This example isn't enough to warrant spending tons of resources supporting this type of diagram. This is more "icon" than "diagram"
Flowchart | [1](https://bevyengine.org/news/bevy-0-6/#render-graphs-and-sub-graphs) | Same as above
Bar Chart | [1](https://bevyengine.org/news/bevy-0-6/#entity-spawn-benchmark-duration-in-microseconds-less-is-better) [2](https://bevyengine.org/news/bevy-0-5/#component-add-remove-benchmark-in-milliseconds-less-is-better) [3](https://bevyengine.org/news/bevy-0-5/#sparse-fragmented-iterator-benchmark-in-nanoseconds-less-is-better) [4](https://bevyengine.org/news/bevy-0-5/#fragmented-iterator-benchmark-in-milliseconds-less-is-better) [5](https://bevyengine.org/news/bevy-0-4/#time-to-compile-change-to-3d-scene-example-in-seconds-less-is-better) [6](https://bevyengine.org/news/bevy-0-4/#frame-time-to-draw-10-000-static-sprites-in-milliseconds-less-is-better) [7](https://bevyengine.org/news/bevy-0-4/#frame-time-to-draw-10-000-moving-sprites-in-milliseconds-less-is-better) [8](https://bevyengine.org/news/bevy-0-4/#frame-time-to-draw-text-debug-example-in-milliseconds-less-is-better) [9](https://bevyengine.org/news/bevy-0-3/#getting-an-entity-s-component-per-100k-in-milliseconds-smaller-is-better) | Due to its already extensive usage, supporting this makes sense
"ECS Overview Diagram" | [1](https://github.com/bevyengine/bevy-website/pull/290#issuecomment-1076737664) | This type of diagram would be extremely useful to display at the start of every example
## Potential Solutions
### [mermaid](https://mermaid-js.github.io/mermaid/#/)
#### What
Javascript framework for rendering various diagrams
#### Pros
- Very easy to create charts and diagrams
- as long as they are the types of diagrams defined by mermaid
- Proven to work with Zola (#377)
#### Cons
- Hard to customize beyond colors and outlines
- Poor layout solver with virtually no control, leading to unreadable diagrams as they grow in size
- Some types of diagrams are better than others
### HTML + CSS
#### What
By using shortcodes in Zola it is _possible_ to create html blocs and display them in a page. However, for that to be composable and useful, we would need to add support for nested shortcodes, in which case we could write shortcodes somewhat similar to a mermaid script.
(Are there other ways to get it working?)
#### Pros
- No javascript or external dependencies needed
#### Cons
- Requires implementing support for nested shortcodes in Zola (something that the maintainer says is very unlikely to happen https://github.com/getzola/zola/issues/515)
### [LaTeX](https://www.latex-project.org/)
#### What
> LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.
[Example of how it looks in use](https://en.wikipedia.org/wiki/LaTeX#How_it_works)
#### Pros
- LaTeX is very powerful
#### Cons
- [Most likely requires getting a plugin-system to work in Zola](https://zola.discourse.group/t/proposal-plugin/975?u=cobalt)
- Can LaTeX solve these various diagrams without adding too much overhead or maintenance concerns?
## Feedback wanted
- Is this something that is valuable to pursue?
- Would solving this improve our current or future situation?
- Are there other types of diagrams we should consider adding to the list above?
- Are there other technologies or approaches that could solve this?
Contributor guide
Research direction
Review the existing Bevy-book and release-note chart examples, then read the linked proposals and Zola discussions. Compare Mermaid, HTML/CSS shortcodes, and LaTeX against the listed diagram needs, customization concerns, and maintenance constraints. Done requires an agreed implementation direction rather than only collecting feedback.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css, html, javascript, latex
- Domain
- documentation, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100