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

Consider removing bullet lists from section overview diagrams

Aperta
#520 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
TeX
Stelle
63
Fork
77
Merge medio
20h 8m
PR unite (30g)
3

Descrizione

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_

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Individua i diagrammi Mermaid rimanenti per le panoramiche delle sezioni nei materiali della lezione e confronta il loro rendering in Mermaid Live e nell’anteprima di GitHub. Esamina le etichette Markdown esistenti, gli elenchi puntati, l'indentazione e la discussione sull'evidenziazione della sezione corrente. Il lavoro è completato quando viene presa una decisione chiara e le panoramiche interessate vengono aggiornate in modo coerente, oppure viene documentato il motivo per cui l'approccio attuale dovrebbe essere mantenuto.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
markdown
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Da chiarire
Idoneità per principianti
25/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.