Update examples in docs

[knsv]

Currently, the examples in the docs folder used on github and the examples on the docs site have different formats. This leads to users on github browsing into the docs folder without seeing the diagrams or broken examples in the docs site.

This should be fixed. So that the md files renders both on github and using docsify.

relates to #3291
@jvaque

[jvaque]

I had a look through previous changes and pull request and saw that mermaid-example was added on #2449 in order to get rid of duplication, and issues reporting lack of examples in the docs.

The next step you mentioned for removing duplicate is a very welcome addition. As there were issues reported in live editor citing lack of example and it'll free up the maintainers from having to keep the copies in sync.

Ref: #2394 (comment)

Originally posted by @sidharthv96 in #2449 (comment)

Maybe a solution could be to add some sort of documentation for the documentation, setting out what each type of code block type mean (from what I've seen so far mermaid, mermaid-example, mmd, mmd2), and how to use them when contributing, or if reading the documentation files.

On a separate note maybe could change from mmd to mermaid-code or mermaid-mmd as from what I've seen it seems to be used when just wanting to show the code but not the graph while in the docs webpage or GitHub.

I haven't come across any broken examples in the docs site but I'm happy to try my best to fix them

[knsv]

Yes, the basic issue is that in order to display both the code and the rendered graph you need two blocks of code at github but only one in dosciify. The docsify code is also available in GitHub then displaying the code not the diagram.

Perhaps we need a transformation step where .md files with mermaid-example blocks which have the code blocks split into mermaid-code and mermaid blocks.

If we do that we need to put some comments in place in the resulting markdown files explaining that they are auto generated and where edits should happen. Here the issue is that people will edit the wrong set of markdown files resulting in lost updates.

The other option is to accept the duplication.

[sidharthv96]

I think we should have the transformation step which runs on push to master that generates the required files and also a linter that runs on PRs which rejects manual edits to the generated files so people won't be able to commit changes to the incorrect files.

[weedySeaDragon]

(jumping in. I've been using PlantUML but have really, really wanted to use a tool that has a properly formed language that can be parsed. Can help getting the documentation cleaned up.)

@sidharthv96 I agree with you in using a "transformation step" that generates the documentation files.

Are you thinking of something like a DangerFile to check if a PR author has changed one of the generated files? Or are you thinking of some other tool? I'm familiar with Danger having worked with it in Ruby. I'm sure there are other tools out there to consider.

Or maybe just a GitHub action like this one? Ensure or Prevent files changed in a PR

[sidharthv96]

I've raised #3401 to address this issue.

• docs has been moved to src/docs.
• A transformer has been added src/docs.mts which does the following
  • Pre commit hook: Build files in src/docs to docs, transforming mermaid-example to mermaid and mermaid-example.
  • CI: Runs in verification mode to see if the generated files from src/docs matches the files in docs and fails if there are any modifications.
• Files in docs have a # THIS IS AN AUTOGENERATED FILE. DO NOT EDIT header, which is stripped by docsify when displaying in the doc website.