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

Consider removing bullet lists from section overview diagrams

Abierto
#520 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
TeX
Estrellas
63
Forks
77
Merge medio
20 h 8 min
PR fusionados (30 d)
3

Descripción

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_

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Localiza los diagramas Mermaid restantes de las descripciones generales de las secciones en los materiales de la lección y compara su representación en Mermaid Live y en la vista previa de GitHub. Revisa las etiquetas Markdown existentes, las listas con viñetas, la sangría y el debate actual sobre el resaltado de la sección actual. La tarea estará terminada cuando se haya tomado una decisión clara y se hayan actualizado de forma coherente las descripciones generales afectadas, o se haya documentado por qué debería mantenerse el enfoque actual.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
markdown
Área
documentation
Tipo de issue
Documentación
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Necesita aclaración
Aptitud para principiantes
25/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.