Document the update process

[pawamoy]

Resolves #239.

I think I managed to get a nice mermaid graph:

One problem though: prettier does not understand markdown admonitions and dedents/breaks them.
Not sure if we should just drop the admonition, or find a way to make prettier happy.

EDIT: ref: prettier/prettier#9154

[pawamoy]

Hmm there was an update of the mermaid plugin and now it doesn't work as expected. Investigating.

EDIT: found the source: fralau/mkdocs-mermaid2-plugin#17

[yajo]

Rebase please.

Also, a rebase should trigger actions, which seem to be forever waiting now.

[pawamoy]

It seems ReadTheDocs is breaking mkdocs.yml by adding contents to it. See how format becomes null instead of !!python/name:mermaid2.fence_mermaid:

 - pymdownx.superfences:
    custom_fences:
    - class: mermaid
      format: null

https://readthedocs.org/api/v2/build/11817460.txt

Properly reported here: readthedocs/readthedocs.org#6889 (comment)

And re-opened here: readthedocs/readthedocs.org#7461

[yajo]

Also, a rebase should trigger actions, which seem to be forever waiting now.

It's nice that now I see the builds got triggered, finally!

And re-opened here: readthedocs/readthedocs.org#7461

Yikes, so then we cannot merge this until that is fixed, right? Or we'd end up breaking our docs...

[pawamoy]

Yikes, so then we cannot merge this until that is fixed, right? Or we'd end up breaking our docs...

Indeed 😢

I don't mind letting this PR sit here until we get some news on that RTD issue 🙂

[yajo]

OK I set it to draft until then, to avoid further reviews.

[pawamoy]

Waiting for readthedocs/readthedocs.org#7507. In the meantime if we really want this now, there's a workaround: we can use <div class="mermaid">...</div> instead of a code-block with fences.

[yajo]

Great idea!

[pawamoy]

Damn, prettier refuses to ignore the div when I wrap it inside <!-- prettier-ignore-start --> comments...

[yajo]

This looks pretty good, but you need to fix the docs build and run pre-commit for it to be merged.

Thanks again!

[pawamoy]

Apparently prettier expects a blank line before the <!-- prettier-ignore-end --> comment for it to work (see this comment)

[yajo]

So how shall we proceed now that readthedocs/readthedocs.org#7507 is fixed?

[pawamoy]

We can now configure superfences for mermaid blocks: https://github.com/fralau/mkdocs-mermaid2-plugin#declaring-the-superfences-extension. If you have access to the Insiders of mkdocs-material (through sponsoring), you can follow this: https://squidfunk.github.io/mkdocs-material/reference/diagrams/#superfences and even remove the dependency to the mermaid plugin

And in the Markdown page, use a proper triple-backticks code block instead of a div with mermaid class. The prettier comments can also be removed I think.

However I don't know when RTD will release this just-merged PR!