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

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}

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;

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

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

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>",
+    renderAux(d, n, "<div$2 class=\"option-list\">$1</div>",
-      "\\begin{description}\n$2\n$1\\end{description}\n", result)
+        "\\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:

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;

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(output.count("<div class=\"option-list\"") == 1)
-    check("""<th align="left">-m</th><td align="left">desc</td>""" in output)
+    check("""<div class="option-list-label">-m</div>""" &
-    check("""<th align="left">-n</th><td align="left">very long desc</td>""" in
+          """<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 output.count("<div class=\"option-list\"") == 2
-    check("""<th align="left">-m</th><td align="left">desc</td>""" in output)
+    check("""<div class="option-list-label">-m</div>""" &
-    check("""<th align="left">-n</th><td align="left">very long desc</td>""" in
+          """<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 output.count("<div class=\"option-list\"") == 2
-    check("""<th align="left">compile</th><td align="left">compile1</td>""" in output)
+    check("""<div class="option-list-label">compile</div>""" &
-    check("""<th align="left">doc</th><td align="left">doc1 cont</td>""" in
+          """<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