restyle RST option lists (#17637)

* WIP: restyle RST option lists * apply similar style to Latex * fix tests * minor visual tweaks * update tests * remove leftover comments
2025-12-28 17:04:41 +00:00 · 2021-04-10 10:49:01 +03:00
parent 08262206d3
commit 2150cd1826
7 changed files with 103 additions and 21 deletions
--- a/config/nimdoc.tex.cfg
+++ b/config/nimdoc.tex.cfg
@@ -50,7 +50,7 @@ doc.file = """
 \usepackage{fancyvrb, courier}
 \usepackage{tabularx}
 \usepackage{hyperref}
-\usepackage{enumitem}  % for enumList and rstfootnote
+\usepackage{enumitem}  % for option list, enumList, and rstfootnote

 \usepackage{xcolor}
 \usepackage[tikz]{mdframed}
@@ -77,6 +77,15 @@ bottomline=false}

 \newenvironment{rstpre}{\VerbatimEnvironment\begingroup\begin{Verbatim}[fontsize=\footnotesize , commandchars=\\\{\}]}{\end{Verbatim}\endgroup}
 \newenvironment{rstfootnote}{\begin{description}[labelindent=1em,leftmargin=1em,labelwidth=2.6em]}{\end{description}}
+\ifdim\linewidth<30em
+  \def\rstoptleftmargin{0.4\linewidth}
+  \def\rstoptlabelwidth{0.35\linewidth}
+\else
+  \def\rstoptleftmargin{12em}
+  \def\rstoptlabelwidth{10.5em}
+\fi
+\newenvironment{rstoptlist}{%
+\begin{description}[font=\sffamily\bfseries,style=nextline,leftmargin=\rstoptleftmargin,labelwidth=\rstoptlabelwidth]}{\end{description}}

 % to pack tabularx into a new environment, special syntax is needed :-(
 \newenvironment{rsttab}[1]{\tabularx{\linewidth}{#1}}{\endtabularx}
--- a/doc/nimdoc.css
+++ b/doc/nimdoc.css
@@ -511,6 +511,33 @@ div.footnote-label {
  min-width: 1.7em;
 }

+div.option-list {
+  border: 0.1em solid var(--border);
+}
+div.option-list-item {
+  padding-left: 12em;
+  padding-right: 0;
+  padding-bottom: 0.3em;
+  padding-top: 0.3em;
+}
+div.odd {
+  background-color: var(--secondary-background);
+}
+div.option-list-label {
+  margin-left: -11.5em;
+  margin-right: 0em;
+  min-width: 11.5em;
+  font-weight: bolder;
+  display: inline-block;
+  vertical-align: top;
+}
+div.option-list-description {
+  width: calc(100% - 1em);
+  padding-left: 1em;
+  padding-right: 0;
+  display: inline-block;
+}
+
 blockquote {
  font-size: 0.9em;
  font-style: italic;
--- a/lib/packages/docutils/rst.nim
+++ b/lib/packages/docutils/rst.nim
@@ -2085,6 +2085,7 @@ proc parseBulletList(p: var RstParser): PRstNode =
 proc parseOptionList(p: var RstParser): PRstNode =
  result = newRstNodeA(p, rnOptionList)
  let col = currentTok(p).col
+  var order = 1
  while true:
    if currentTok(p).col == col and isOptionList(p):
      var a = newRstNode(rnOptionGroup)
@@ -2107,6 +2108,7 @@ proc parseOptionList(p: var RstParser): PRstNode =
      if currentTok(p).kind == tkIndent: inc p.idx
      c.add(a)
      c.add(b)
+      c.order = order; inc order
      result.add(c)
    else:
      if currentTok(p).kind != tkEof: dec p.idx  # back to tkIndent
--- a/lib/packages/docutils/rstast.nim
+++ b/lib/packages/docutils/rstast.nim
@@ -90,7 +90,7 @@ type
      level*: int             ## level of headings starting from 1 (main
                              ## chapter) to larger ones (minor sub-sections)
                              ## level=0 means it's document title or subtitle
-    of rnFootnote, rnCitation, rnFootnoteRef:
+    of rnFootnote, rnCitation, rnFootnoteRef, rnOptionListItem:
      order*: int             ## footnote order (for auto-symbol footnotes and
                              ## auto-numbered ones without a label)
    else:
@@ -368,7 +368,7 @@ proc renderRstToStr*(node: PRstNode, indent=0): string =
    result.add txt
  of rnHeadline, rnOverline, rnMarkdownHeadline:
    result.add "\tlevel=" & $node.level
-  of rnFootnote, rnCitation, rnFootnoteRef:
+  of rnFootnote, rnCitation, rnFootnoteRef, rnOptionListItem:
    result.add (if node.order == 0:   "" else: "\torder=" & $node.order)
  else:
    discard
--- a/lib/packages/docutils/rstgen.nim
+++ b/lib/packages/docutils/rstgen.nim
@@ -1165,7 +1165,7 @@ proc renderRstToOut(d: PDoc, n: PRstNode, result: var string) =
    renderAux(d, n, "<dl$2 class=\"docutils\">$1</dl>\n",
                    "\\begin{description}\n$2\n$1\\end{description}\n", result)
  of rnDefItem: renderAux(d, n, result)
-  of rnDefName: renderAux(d, n, "<dt$2>$1</dt>\n", "$2\\item[$1] ", result)
+  of rnDefName: renderAux(d, n, "<dt$2>$1</dt>\n", "$2\\item[$1]\\  ", result)
  of rnDefBody: renderAux(d, n, "<dd$2>$1</dd>\n", "$2\n$1\n", result)
  of rnFieldList:
    var tmp = ""
@@ -1189,14 +1189,20 @@ proc renderRstToOut(d: PDoc, n: PRstNode, result: var string) =
  of rnIndex:
    renderRstToOut(d, n.sons[2], result)
  of rnOptionList:
-    renderAux(d, n, "<table$2 frame=\"void\">$1</table>",
-      "\\begin{description}\n$2\n$1\\end{description}\n", result)
+    renderAux(d, n, "<div$2 class=\"option-list\">$1</div>",
+        "\\begin{rstoptlist}$2\n$1\\end{rstoptlist}", result)
  of rnOptionListItem:
-    renderAux(d, n, "<tr>$1</tr>\n", "$1", result)
+    var addclass = if n.order mod 2 == 1: " odd" else: ""
+    renderAux(d, n,
+        "<div class=\"option-list-item" & addclass & "\">$1</div>\n",
+        "$1", result)
  of rnOptionGroup:
-    renderAux(d, n, "<th align=\"left\">$1</th>", "\\item[$1]", result)
+    renderAux(d, n,
+        "<div class=\"option-list-label\">$1</div>",
+        "\\item[$1]", result)
  of rnDescription:
-    renderAux(d, n, "<td align=\"left\">$1</td>\n", " $1\n", result)
+    renderAux(d, n, "<div class=\"option-list-description\">$1</div>",
+        " $1\n", result)
  of rnOption, rnOptionString, rnOptionArgument:
    doAssert false, "renderRstToOut"
  of rnLiteralBlock:
--- a/nimdoc/testproject/expected/nimdoc.out.css
+++ b/nimdoc/testproject/expected/nimdoc.out.css
@@ -511,6 +511,33 @@ div.footnote-label {
  min-width: 1.7em;
 }

+div.option-list {
+  border: 0.1em solid var(--border);
+}
+div.option-list-item {
+  padding-left: 12em;
+  padding-right: 0;
+  padding-bottom: 0.3em;
+  padding-top: 0.3em;
+}
+div.odd {
+  background-color: var(--secondary-background);
+}
+div.option-list-label {
+  margin-left: -11.5em;
+  margin-right: 0em;
+  min-width: 11.5em;
+  font-weight: bolder;
+  display: inline-block;
+  vertical-align: top;
+}
+div.option-list-description {
+  width: calc(100% - 1em);
+  padding-left: 1em;
+  padding-right: 0;
+  display: inline-block;
+}
+
 blockquote {
  font-size: 0.9em;
  font-style: italic;
--- a/tests/stdlib/trstgen.nim
+++ b/tests/stdlib/trstgen.nim
@@ -1255,7 +1255,7 @@ Test1
    doAssert "<dl id=\"target003\""    in output1
    doAssert "<p id=\"target004\""     in output1
    doAssert "<table id=\"target005\"" in output1  # field list
-    doAssert "<table id=\"target006\"" in output1  # option list
+    doAssert "<div id=\"target006\""   in output1  # option list
    doAssert "<pre id=\"target007\""   in output1
    doAssert "<blockquote id=\"target009\"" in output1
    doAssert "<table id=\"target010\"" in output1  # just table
@@ -1370,9 +1370,12 @@ Test1
    let output = input.toHtml
    check(output.count("<ul") == 1)
    check(output.count("<li>") == 2)
-    check(output.count("<table") == 1)
-    check("""<th align="left">-m</th><td align="left">desc</td>""" in output)
-    check("""<th align="left">-n</th><td align="left">very long desc</td>""" in
+    check(output.count("<div class=\"option-list\"") == 1)
+    check("""<div class="option-list-label">-m</div>""" &
+          """<div class="option-list-description">desc</div></div>""" in
+          output)
+    check("""<div class="option-list-label">-n</div>""" &
+          """<div class="option-list-description">very long desc</div></div>""" in
          output)

  test "Option lists 2":
@@ -1385,11 +1388,15 @@ Test1
      -d  option"""
    let output = input.toHtml
    check(output.count("<ul") == 1)
-    check(output.count("<table") == 2)
-    check("""<th align="left">-m</th><td align="left">desc</td>""" in output)
-    check("""<th align="left">-n</th><td align="left">very long desc</td>""" in
+    check output.count("<div class=\"option-list\"") == 2
+    check("""<div class="option-list-label">-m</div>""" &
+          """<div class="option-list-description">desc</div></div>""" in
          output)
-    check("""<th align="left">-d</th><td align="left">option</td>""" in
+    check("""<div class="option-list-label">-n</div>""" &
+          """<div class="option-list-description">very long desc</div></div>""" in
+          output)
+    check("""<div class="option-list-label">-d</div>""" &
+          """<div class="option-list-description">option</div></div>""" in
          output)
    check "<p>option</p>" notin output

@@ -1402,11 +1409,15 @@ Test1
      -d  option"""
    let output = input.toHtml
    check(output.count("<ul") == 1)
-    check(output.count("<table") == 2)
-    check("""<th align="left">compile</th><td align="left">compile1</td>""" in output)
-    check("""<th align="left">doc</th><td align="left">doc1 cont</td>""" in
+    check output.count("<div class=\"option-list\"") == 2
+    check("""<div class="option-list-label">compile</div>""" &
+          """<div class="option-list-description">compile1</div></div>""" in
          output)
-    check("""<th align="left">-d</th><td align="left">option</td>""" in
+    check("""<div class="option-list-label">doc</div>""" &
+          """<div class="option-list-description">doc1 cont</div></div>""" in
+          output)
+    check("""<div class="option-list-label">-d</div>""" &
+          """<div class="option-list-description">option</div></div>""" in
          output)
    check "<p>option</p>" notin output