Explain black magic of `Calendar.from_jcal` in API design reference docs

[stevepiercy]

This looks like black magic to me because the link to the method does not align with the code sample. There's no Calendar.from_jcal method in the icalendar.cal.calendar module, yet the code example works! Is the black magic in icalendar.cal.component?

I think we need to explain this black magic somewhere in the API design document, and reference it here in the description of the code example.

Originally posted by @stevepiercy in #1122 (comment)

[niccokunzmann]

Since we include the members now and had a call, can this be closed or is there more to do?

[stevepiercy]

It needs to be documented in both the API design document and in the reorganization of Usage. Newcomers won't know about its design or how to use it.

What's a good example in the code base that demonstrates the design?

[niccokunzmann]

I created two class diagrams.

The left one is for inheritance, e.g. of methods.
The right one for runtime composition of objects: The calendar contains events, events contain Alarms.
I can create a PR with a bit of text. Also, this is an SVG, so parts of it can be clickable.
What do you think?

[stevepiercy]

That sounds like a good start.

We have options for diagrams.

• Mermaid diagrams sphinxcontrib.mermaid allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts. There's also an online editor, Mermaid Playground to make diagrams prettier.

• There's an option autoclasstree that might do exactly what we want. Search for the term in its usage documentation at https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/. I've never used it, so I'm interested to see what it yields.

• https://6.docs.plone.org/contributing/documentation/myst-reference.html#diagrams-and-graphs-with-mermaid for sample Mermaid syntax. That's in MyST, so it would need to be adapted to reST:

  .. mermaid::
      :options:
      
      Mermaid code

• Alternatively, sphinx.ext.inheritance_diagram. Its diagrams aren't very pretty, and it appears to render output only to PNG, but perhaps they can be tweaked.

• https://6.docs.plone.org/contributing/documentation/myst-reference.html#diagrams-and-graphs-with-graphviz

[niccokunzmann]

I don't really want to spend time on these diagrams. I have placed the classes in the one above so that they stay in the same place, yet reflecting the runtime and the class functionality. If the one above + explanation works for you, then I can add it and document a bit more. Probably in the Design section? What are your thoughts on this?

[stevepiercy]

It's a PNG, not an SVG.

I don't understand why there's four columns for the chart on the left, but only three on the right.

I'm concerned about the display of diagrams on narrow devices.

What did you use to create the diagrams? How do we update it?

Mermaid is nice. Generating diagrams from code is easier to maintain, especially whenever the API changes. I played around with it, and could create a basic illustrative example of class inheritance, for example, of a single property.

Anyway, I think that the diagrams are beside the point of this issue. The narrative explanation is much more important. Diagrams and code examples could enhance the narrative documentation, but they shouldn't be the focus.

[niccokunzmann]

What do you think of this: Could you open a PR to close the issue, so that the description is worded from a perspective of someone who is not too much into the technical details (as can happen to me) and then I have a review and see if it is technically correct?

[stevepiercy]

heh, I'm not clear myself. That's why I opened this issue. To gain clarity. Although we chatted, but it didn't stick.

[niccokunzmann]

Hm. Let's have another chat, you ask questions, we write them down and make sure the document answers them. You can also write them here. I like chats, too.