Fixes: Insert a Mermaid diagram in docs/contributing/core/package-dependencies.md

[jensens]

Fixes #1683

---

📚 Documentation preview 📚: https://plone6--1715.org.readthedocs.build/

[stevepiercy]

Unfortunately we cannot support Mermaid diagrams in plone-sphinx-theme. See:

• 0.9.2: pep517 based build fails mgaitan/sphinxcontrib-mermaid#137
• Looking for maintainers for sphinxcontrib-mermaid mgaitan/sphinxcontrib-mermaid#148

I would love to support mermaid, but until that issue is resolved, I can't merge this PR. We can keep it open until then.

[jensens]

Unfortunately we cannot support Mermaid diagrams in plone-sphinx-theme

Yay.

[stevepiercy]

@jensens let's revisit this. See #1777.

[stevepiercy]

@jensens I went ahead and did a review by directly editing the file. I approve. Is this ready to merge? It's marked as Draft.

Check it out: https://plone6--1715.org.readthedocs.build/contributing/core/package-dependencies.html

[stevepiercy]

@jensens I made a couple of enhancements to the Mermaid diagrams. Now they have alt, caption, and zoom attributes.

I don't understand the second diagram, but it's pretty.

[stevepiercy]

@jensens would you please take a look at the pull request preview at https://plone6--1715.org.readthedocs.build/conceptual-guides/package-dependencies.html and let me know if this is ready to merge or you want to make any changes? I moved it into the Conceptual Guides from contributing to Plone core, since this is not really a how-to guide. Thank you!

[stevepiercy]

@jensens can you please explain how you generated the mermaid diagrams?

I can update the docs accordingly. I would gratefully accept any notes you can create, anything that helps as reproduce what you did with these three diagrams. Maybe we can automate it. Thank you!

[jensens]

@jensens can you please explain how you generated the mermaid diagrams?

I can update the docs accordingly. I would gratefully accept any notes you can create, anything that helps as reproduce what you did with these three diagrams. Maybe we can automate it. Thank you!

I used https://www.mermaidchart.com/ to get a preview of the diagram I wrote and copied it over.

[stevepiercy]

@jensens that's a nice tool.

Did you use any other sources of data to put into the diagrams, such as a requirements file or some other dependency generator?

I'm concerned that diagrams will not be updated with each release because no one knows how to maintain them.

I also notice that we need to increase contrast in dark mode for the diagram, as some lines do not show up.

[jensens]

Did you use any other sources of data to put into the diagrams, such as a requirements file or some other dependency generator?

This is out of my head. It is an architectural overview, not something one can generate. The level of abstraction is nowhere in our metadata.

The section "Packages in detail" could be generated - with some curation afterwards.

I'm concerned that diagrams will not be updated with each release because no one knows how to maintain them.

Indeed, we need to review them with each major release.

I also notice that we need to increase contrast in dark mode for the diagram, as some lines do not show up.

It seems to be an issue with the theme, as the background of the mermaid diagram changes to black.

[stevepiercy]

For how to generate the diagrams and the section Packages in detail, I can ask @mauritsvanrees to add items to the release checklist. Any written notes for how to update these items would be great to have outside of your brain.

For the contrast of the Mermaid diagram on dark mode, I am reluctant to change the default background color of the pre selector, which is what all transparent SVG images use, because it would mess up the display and contrast of code blocks. The upstream themes PyData Sphinx Theme and Sphinx Book Themes have the resources to test usability and accessibility, but Plone Sphinx Theme is just me at the moment.

I would prefer to edit the SVG and add greater contrast as needed and test it, but then how do we collaborate on it going forward? As soon as you generate a new Mermaid diagram, any changes I put into it to fix the contrast would be obliterated.

[stevepiercy]

@jensens oh, I'm an idiot. Duh, the source of the SVG as right there! I'll see if I can tweak it with some settings using that online tool.

[stevepiercy]

@jensens I fiddled around with the source of the Mermaid diagram, and it now has some contrast, not sufficient for accessibility, but better than before, so I'll take it.

Is this ready to merge? I know it's not complete, but this is a vast improvement from where we are currently, and we can always iterate to improve it. I can also create new issues for anyone to pick up. Please let me know.

[stevepiercy]

@mauritsvanrees where do you keep your release checklist? Let's add these to it, noting that the first two links are not yet live, but will be upon a merge of this PR.

• Update Mermaid diagrams and Packages in detail in documentation.
  • Source: https://github.com/plone/documentation/blob/6.0/docs/conceptual-guides/package-dependencies.md
  • Rendered: https://6.docs.plone.org/conceptual-guides/package-dependencies.html
  • Editing tool: https://www.mermaidchart.com/play
  • Pick @jensens's 🧠 for updates

[mauritsvanrees]

The release checklist is in the coredev buildout. Each branch (6.0, 6.1) has its own slightly different list.

But the list of packages hardly ever changes. There are differences between 6.0 and 6.1 of course, but now that 6.1 is in beta, I don't expect any changes until 6.2 or 7. So adding this to the checklist may not be useful very often.

[stevepiercy]

@mauritsvanrees pull request created at plone/buildout.coredev#968

I left out the Mermaid diagrams after all, now that I have a better grasp of their intent to describe a concept without overwhelming detail.