Auto transform mermaid-example in docs.

[sidharthv96]

📑 Summary

mermaid-example blocks were not rendered in GitHub.
Added a build step for docs which adds a mermaid block for each mermaid-example, so that it's rendered in Github.

If anyone makes manual changes to docs, lint will fail indicating what to do.

Resolves #3315

📏 Design Decisions

By parsing the AST and injecting directly, it will work for any complex structure.
We could also introduce grammar & spell checks to docs in future easily.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 🔖 targeted develop branch

[sidharthv96]

Collapsing both docs folder will help for an easy review.

[sidharthv96]

@weedySeaDragon @dbartholomae, https://danger.systems/js/ seems like a good choice to integrate some additional checks. Have you worked with anything better, or should we go ahead with danger?

[dbartholomae]

I haven't worked with danger yet, but heard good things, so I don't see a reason not to go ahead with it.
I've used two different methods so far:

1. A simple 4-line bash script in a separate workflow that is triggered on merge to main, runs the build script (first line) and then adds/commits/pushes (the other three lines).
2. Building and committing changed docs as part of a semantic-release process, see e.g. this repo.

Running the build on push to main instead of running it on PR change has the advantage that it doesn't run over and over when there are stil discussions and changes going on. The disadvantage is that it's possible for a PR to change the output files only without realizing that this will be overwritten right after merge.

[sidharthv96]

Will need some work after #3408 is merged.

[sidharthv96]

The disadvantage is that it's possible for a PR to change the output files only without realizing that this will be overwritten right after merge.

@dbartholomae this is exactly why the current CI fails if there is any difference.

it doesn't run over and over when there are stil discussions and changes going on.

As the current doc lint takes only 7 seconds extra, I think it's a valid tradeoff.

Sidenote: We should really introduce proper changelog along with releases.

[knsv]

Looks great! Hopefully this will improve readability on GitHub without making the docs side hard to maintain!

[weedySeaDragon]

(Realize this has been closed)
Sorry I didn't have a chance to comment. This is a good step forward.

[sidharthv96]

@weedySeaDragon we merged this as we had multiple PRs that might conflict with this.

We'll be doing the rest of the work in a new, (hopefully smaller) PR.

[CalebUsadi]

This process seems to add unnecessary complexity to the documentation. It complicates the build and development process; contrary to contributing.md, docsify serve docs does not allow for live reloading of the server, because modifications to src/docs don't update the live server; the "edit this page" link in any documentation page doesn't actually open to the editable file and displays a harsh, inaccessible warning; the repo contains significant redundant code and extra files to support the build process. The only advantage is the elimination of redundant code chunks in the documentation, which does not outweigh the drawbacks. I would like to reopen this issue and refactor the documentation, which I will do in a branch I create.

[sidharthv96]

There is a complete documentation overhaul going on in #3678

I understand the main concerns are:

1. Absence of live update (need to fix added in Live edits for Docs #3755)
2. Edit page link is wrong (fixed in docs: Add link to docs source #3612)
3. Redundant code

[CalebUsadi]

Thank you!