Keep the doc sidebar on the screen while scrolling (#19851)

* [docgen] Group sidebar sections into <details> (open by default)

* [docgen] Consistent indentation in generated HTML

(this is a boon for working on docgen's html/css output)

* [docgen] Move Source/Edit buttons inside main div

This makes styling the documentation significantly easier.

* [docgen] Somewhat consistent CSS formatting

* [docgen] Keep the sidebar onscreen while scrolling

* [docgen] Tweak CSS for the sticky sidebar

* [docgen] search type=text ==> type=search

* [docgen] Update expected doc output

* [docgen] Fix Group by Type sidebar placement bug

* [docgen] Curse you, whitespace (fix tests)

* [docgen] Fix rst2html tests

Co-authored-by: sandytypical <43030857+xflywind@users.noreply.github.com>

1 files changed, 103 insertions, 113 deletions

diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg
index 4efa1f637..725f9e0a5 100644
--- a/config/nimdoc.cfg
+++ b/config/nimdoc.cfg
@@ -9,25 +9,28 @@ split.item.toc = "20"
 
 doc.section = """
 <div class="section" id="$sectionID">
-<h1><a class="toc-backref" href="#$sectionID">$sectionTitle</a></h1>
-<dl class="item">
-$content
-</dl></div>
+  <h1><a class="toc-backref" href="#$sectionID">$sectionTitle</a></h1>
+  <dl class="item">
+    $content
+  </dl>
+</div>
 """
 
 doc.section.toc = """
 <li>
-  <a class="reference reference-toplevel" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a>
-  <ul class="simple simple-toc-section">
-    $content
-  </ul>
+  <details open>
+    <summary><a class="reference reference-toplevel" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a></summary>
+    <ul class="simple simple-toc-section">
+      $content
+    </ul>
+  </details>
 </li>
 """
 
 doc.section.toc2 = """
-  <ul class="simple nested-toc-section">$plainName
-    $content
-  </ul>
+<ul class="simple nested-toc-section">$plainName
+  $content
+</ul>
 """
 
 # Chunk of HTML emitted for each entry in the HTML table of contents.
@@ -47,12 +50,12 @@ doc.section.toc2 = """
 
 doc.item = """
 <div id="$itemSymOrID">
-<dt><pre>$header</pre></dt>
-<dd>
-$deprecationMsg
-$desc
-$seeSrc
-</dd>
+  <dt><pre>$header</pre></dt>
+  <dd>
+    $deprecationMsg
+    $desc
+    $seeSrc
+  </dd>
 </div>
 """
 
@@ -61,9 +64,8 @@ $seeSrc
 # * $overloadGroupName - the anchor for this whole group
 # * $content - string containing `doc.item`s themselves
 doc.item2 = """
-
 <div id="$overloadGroupName">
-$content
+  $content
 </div>
 """
 
@@ -73,18 +75,14 @@ $content
 # This is used for TOC items which are not overloadable (e.g. types).
 # `$header_plain` would be too verbose here, so we use $name.
 doc.item.toc = """
-  <li><a class="reference" href="#$itemSymOrIDEnc"
-    title="$header_plain">$name</a></li>
+<li><a class="reference" href="#$itemSymOrIDEnc" title="$header_plain">$name</a></li>
 """
 
 # This is used for TOC items which are grouped by the same name (e.g. procs).
 doc.item.tocTable = """
-  <li><a class="reference" href="#$itemSymOrIDEnc"
-    title="$header_plain">$header_plain</a></li>
+<li><a class="reference" href="#$itemSymOrIDEnc" title="$header_plain">$header_plain</a></li>
 """
 
-
-
 # HTML rendered for doc.item's seeSrc variable. Note that this will render to
 # the empty string if you don't pass anything through --git.url. Available
 # substitutaion variables here are:
@@ -94,32 +92,31 @@ doc.item.tocTable = """
 # * $line: line of the item in the original source file.
 # * $url: whatever you did pass through the --git.url switch (which also
 #   gets variables path/line replaced!)
-doc.item.seesrc = """&nbsp;&nbsp;<a
-href="${url}/tree/${commit}/${path}#L${line}"
-class="link-seesrc" target="_blank">Source</a>
-&nbsp;&nbsp;<a href="${url}/edit/${devel}/${path}#L${line}" class="link-seesrc" target="_blank" >Edit</a>
+doc.item.seesrc = """
+<a href="${url}/tree/${commit}/${path}#L${line}" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
+<a href="${url}/edit/${devel}/${path}#L${line}" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
 """
 
 doc.deprecationmsg = """
-  <div class="deprecation-message">
-    <b>$label</b> $message
-  </div>
+<div class="deprecation-message">
+  <b>$label</b> $message
+</div>
 """
 
 doc.toc = """
 <ul class="simple simple-toc" id="toc-list">
-$content
+  $content
 </ul>
 """
 
 doc.body_toc_groupsection = """
-  <div class="search-groupby">
-    Group by:
-    <select onchange="groupBy(this.value)">
-      <option value="section">Section</option>
-      <option value="type">Type</option>
-    </select>
-  </div>
+<div class="search-groupby">
+  Group by:
+  <select onchange="groupBy(this.value)">
+    <option value="section">Section</option>
+    <option value="type">Type</option>
+  </select>
+</div>
 """
 
 @if boot:
@@ -130,36 +127,36 @@ doc.body_toc_groupsection = """
 doc.body_toc_group = """
 <div class="row">
   <div class="three columns">
-  <div class="theme-switch-wrapper">
-    <label class="theme-switch" for="checkbox">
-      <input type="checkbox" id="checkbox" />
-      <div class="slider round"></div>
-    </label>
-    &nbsp;&nbsp;&nbsp; <em>Dark Mode</em>
-  </div>
-  <div id="global-links">
-    <ul class="simple-boot">
-      <li><a href="manual.html">Manual</a></li>
-      <li><a href="lib.html">Standard library</a></li>
-      <li> <a href="$theindexhref">Index</a></li>
-      <li><a href="compiler/$theindexhref">Compiler docs</a></li>
-      <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
-      <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
-    </ul>
-  </div>
-  <div id="searchInputDiv">
-    Search: <input type="text" id="searchInput"
-      onkeyup="search()" />
-  </div>
-  $body_toc_groupsection
-  $tableofcontents
+    <div class="theme-switch-wrapper">
+      <label class="theme-switch" for="checkbox">
+        <input type="checkbox" id="checkbox" />
+        <div class="slider round"></div>
+      </label>
+      &nbsp;&nbsp;&nbsp; <em>Dark Mode</em>
+    </div>
+    <div id="global-links">
+      <ul class="simple-boot">
+        <li><a href="manual.html">Manual</a></li>
+        <li><a href="lib.html">Standard library</a></li>
+        <li> <a href="$theindexhref">Index</a></li>
+        <li><a href="compiler/$theindexhref">Compiler docs</a></li>
+        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
+        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
+      </ul>
+    </div>
+    <div id="searchInputDiv">
+      Search: <input type="search" id="searchInput"
+        onkeyup="search()" />
+    </div>
+    $body_toc_groupsection
+    <div id="tocRoot"></div>
+    $tableofcontents
   </div>
-  $seeSrc
   <div class="nine columns" id="content">
-  <div id="tocRoot"></div>
-  $deprecationMsg
-  <p class="module-desc">$moduledesc</p>
-  $content
+    $seeSrc
+    $deprecationMsg
+    <p class="module-desc">$moduledesc</p>
+    $content
   </div>
 </div>
 """
@@ -169,39 +166,36 @@ doc.body_toc_group = """
 doc.body_toc_group = """
 <div class="row">
   <div class="three columns">
-  <div class="theme-switch-wrapper">
-    <label class="theme-switch" for="checkbox">
-      <input type="checkbox" id="checkbox" />
-      <div class="slider round"></div>
-    </label>
-    &nbsp;&nbsp;&nbsp; <em>Dark Mode</em>
-  </div>
-  <div id="global-links">
-    <ul class="simple">
-    <li>
-      <a href="$theindexhref">Index</a>
-    </li>
-    </ul>
-  </div>
-  <div id="searchInputDiv">
-    Search: <input type="text" id="searchInput"
-      onkeyup="search()" />
-  </div>
-  <div>
-    Group by:
-    <select onchange="groupBy(this.value)">
-      <option value="section">Section</option>
-      <option value="type">Type</option>
-    </select>
-  </div>
-  $tableofcontents
+    <div class="theme-switch-wrapper">
+      <label class="theme-switch" for="checkbox">
+        <input type="checkbox" id="checkbox" />
+        <div class="slider round"></div>
+      </label>
+      &nbsp;&nbsp;&nbsp; <em>Dark Mode</em>
+    </div>
+    <div id="global-links">
+      <ul class="simple">
+        <li><a href="$theindexhref">Index</a></li>
+      </ul>
+    </div>
+    <div id="searchInputDiv">
+      Search: <input type="search" id="searchInput" onkeyup="search()"/>
+    </div>
+    <div>
+      Group by:
+      <select onchange="groupBy(this.value)">
+        <option value="section">Section</option>
+        <option value="type">Type</option>
+      </select>
+    </div>
+    <div id="tocRoot"></div>
+    $tableofcontents
   </div>
-  $seeSrc
   <div class="nine columns" id="content">
-  <div id="tocRoot"></div>
-  $deprecationMsg
-  <p class="module-desc">$moduledesc</p>
-  $content
+    $seeSrc
+    $deprecationMsg
+    <p class="module-desc">$moduledesc</p>
+    $content
   </div>
 </div>
 """
@@ -220,14 +214,13 @@ doc.listing_end = "</pre>"
 
 # * $analytics: Google analytics location, includes <script> tags
 doc.file = """<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <!--  This file is generated by Nim. -->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>$title</title>
 
 <!-- Favicon -->
 <link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
@@ -238,27 +231,24 @@ doc.file = """<?xml version="1.0" encoding="utf-8" ?>
 <link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
 
 <!-- CSS -->
-<title>$title</title>
 <link rel="stylesheet" type="text/css" href="$nimdoccss">
 
+<!-- JS -->
 <script type="text/javascript" src="$dochackjs"></script>
-
 </head>
 <body>
-<div class="document" id="documentId">
-  <div class="container">
-    <h1 class="title">$title</h1>$subtitle
-    $content
-    <div class="row">
+  <div class="document" id="documentId">
+    <div class="container">
+      <h1 class="title">$title</h1>$subtitle
+      $content
       <div class="twelve-columns footer">
         <span class="nim-sprite"></span>
-        <br/>
+        <br>
         <small style="color: var(--hint);">Made with Nim. Generated: $date $time UTC</small>
       </div>
     </div>
   </div>
-</div>
-$analytics
+  $analytics
 </body>
 </html>
 """