bevyengine / bevyengine/bevy-website

Add a way to draw charts, graphs and diagrams from markdown / code / text

Open
#378 3 comments 0 reactions 0 assignees View on GitHub
A-Book C-Feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.