carpentries-incubator / carpentries-incubator/python-intermediate-development

Consider removing bullet lists from section overview diagrams

Offen
#520 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
TeX
Sterne
63
Forks
77
Ø Merge
20 Std. 8 Min.
Gemergte PRs (30 T.)
3

Beschreibung

As detailed in comment below, we should consider if we actually want to include a bullet list in the section overviews. It is not displayed terribly well at the moment, but it is legible, so I don't think this is a hard fault, but it is probably worth the consideration. I think we should also have a go at "highlighting" the current section in the flow diagram, since that would at least add some value to having this at the top of each section; otherwise, it is the same diagram for each if we remove the bullet points!

---

Thanks @bielsnohr for having a go with the Markdown list formatting and also investigating the `alt` / `accDescr` behaviour.

Annoyingly it seems that the Mermaid Markdown support is only for inline level formatting such as bold / italic not any block elements like lists, and further that in current Mermaid renderer versions setting the text alignment of labels using a style directive like `style nodeid text-align:left` has no effect. Looking at the SVG / HTML produced with a style directive added, while the style information does get correctly applied to the outer node element and inner `span` containing the label, it has no effect on the `span` element as this `text-align` only works for block display elements like `div`s, and the `span` element is nested inside a `div` for which `text-align` is fixed to `center`. From [a previous StackOverflow question / answer on this issue](https://stackoverflow.com/q/76961008) it seems this wasn't always the case.

It seems like there is still some benefit to wrapping the labels in ``"`...`"`` as [from the Mermaid documentation](https://mermaid.ai/open-source/syntax/flowchart.html#markdown-strings) it seems like this should preserve any newlines in label text without needing to manually include `
` tags. Unfortunately it seems that common whitespace at the beginning of lines (for example from indenting diagram syntax) is not stripped and effect the rendered output. I have suggested changing the remaining section overview Mermaid diagrams to use Markdown labels for the bulleted lists and reduced the whitespace at the beginning of the list items to a single indent level, as this makes them display slightly more nicely on Mermaid Live and GitHub preview for me. We could also remove all indentation from the list items but then this makes the diagram syntax difficult to read.

Possibly given issues with formatting long text segments in Mermaid diagrams we might want to revisit whether to continue to have the detailed section breakdowns in the overviews in Mermaid rather than as a separate bulleted list, but I think this is probably better dealt with in another issue / PR.

_Originally posted by @matt-graham in https://github.com/carpentries-incubator/python-intermediate-development/pull/513#pullrequestreview-3840118311_

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Finde die verbleibenden Mermaid-Diagramme für Abschnittsübersichten in den Unterrichtsmaterialien und vergleiche ihre Darstellung in Mermaid Live und der GitHub-Vorschau. Prüfe die vorhandenen Markdown-Beschriftungen, Aufzählungslisten, Einrückungen und die Diskussion zur Hervorhebung des aktuellen Abschnitts. Die Aufgabe ist erledigt, wenn eine klare Entscheidung getroffen und die betroffenen Übersichten einheitlich aktualisiert wurden oder dokumentiert wurde, warum der aktuelle Ansatz beibehalten werden sollte.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
markdown
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.