Merge pull request #9103 from kaushalmodi/encode-urls-in-docs

Encode non-alphanum chars like %, + in URLs in the docs

6 files changed, 31 insertions, 19 deletions

diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg
index 96e91283a..960c58c9e 100644
--- a/config/nimdoc.cfg
+++ b/config/nimdoc.cfg
@@ -38,7 +38,8 @@ doc.section.toc = """
 # * $seeSrc: generated HTML from doc.item.seesrc (if some switches are used).
 
 doc.item = """
-<dt id="$itemSym"><a name="$itemSymOrID"></a><pre>$header</pre></dt>
+<a id="$itemSymOrIdEnc"></a>
+<dt><pre>$header</pre></dt>
 <dd>
 $desc
 $seeSrc
@@ -48,7 +49,7 @@ $seeSrc
 # Chunk of HTML emitted for each entry in the HTML table of contents.
 # See doc.item for available substitution variables.
 doc.item.toc = """
-  <li><a class="reference" href="#$itemSymOrID"
+  <li><a class="reference" href="#$itemSymOrIDEnc"
     title="$header_plain">$name<span class="attachedType" style="visibility:hidden">$attype</span></a></li>
 """
 
diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim
index 51bb9c757..232da5c93 100644
--- a/lib/packages/docutils/rstgen.nim
+++ b/lib/packages/docutils/rstgen.nim
@@ -424,11 +424,15 @@ proc sortIndex(a: var openArray[IndexEntry]) =
     if h == 1: break
 
 proc escapeLink(s: string): string =
+  ## This proc is mostly copied from uri/encodeUrl except that
+  ## these chars are also left unencoded: '#', '/'.
   result = newStringOfCap(s.len + s.len shr 2)
   for c in items(s):
     case c
-    of 'a'..'z', '_', 'A'..'Z', '0'..'9', '.', '#', ',', '/':
-      result.add c
+    of 'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~': # same as that in uri/encodeUrl
+      add(result, c)
+    of '#', '/': # example.com/foo/#bar (don't escape the '/' and '#' in such links)
+      add(result, c)
     else:
       add(result, "%")
       add(result, toHex(ord(c), 2))
@@ -444,7 +448,7 @@ proc generateSymbolIndex(symbols: seq[IndexEntry]): string =
     var j = i
     while j < symbols.len and keyword == symbols[j].keyword:
       let
-        url = symbols[j].link #.escapeLink
+        url = symbols[j].link.escapeLink
         text = if symbols[j].linkTitle.len > 0: symbols[j].linkTitle else: url
         desc = if symbols[j].linkDesc.len > 0: symbols[j].linkDesc else: ""
       if desc.len > 0:
diff --git a/lib/pure/uri.nim b/lib/pure/uri.nim
index dd8040928..d296017dd 100644
--- a/lib/pure/uri.nim
+++ b/lib/pure/uri.nim
@@ -60,6 +60,7 @@ proc encodeUrl*(s: string, usePlus=true): string =
   let fromSpace = if usePlus: "+" else: "%20"
   for c in s:
     case c
+    # https://tools.ietf.org/html/rfc3986#section-2.3
     of 'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~': add(result, c)
     of ' ': add(result, fromSpace)
     else:
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
index 285d09d5c..d81be8f48 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -1250,7 +1250,7 @@ function main() {
 <li>
   <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#someType,"
+      <li><a class="reference" href="#someType%2C"
     title="someType(): SomeType"><wbr />some<wbr />Type<span class="attachedType" style="visibility:hidden">SomeType</span></a></li>
 
   </ul>
@@ -1265,7 +1265,8 @@ function main() {
   <div class="section" id="7">
 <h1><a class="toc-backref" href="#7">Types</a></h1>
 <dl class="item">
-<dt id="SomeType"><a name="SomeType"></a><pre><a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
+<a id="SomeType"></a>
+<dt><pre><a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
   <span class="Identifier">enumValueA</span><span class="Other">,</span> <span class="Identifier">enumValueB</span><span class="Other">,</span> <span class="Identifier">enumValueC</span></pre></dt>
 <dd>
 
@@ -1276,7 +1277,8 @@ function main() {
 <div class="section" id="12">
 <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <dl class="item">
-<dt id="someType"><a name="someType,"></a><pre><span class="Keyword">proc</span> <span class="Identifier">someType</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
+<a id="someType%2C"></a>
+<dt><pre><span class="Keyword">proc</span> <span class="Identifier">someType</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
 <dd>
 constructor.
 
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 064a70011..f1c567627 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -1255,7 +1255,7 @@ function main() {
 <li>
   <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#bar,T,T"
+      <li><a class="reference" href="#bar%2CT%2CT"
     title="bar[T](a, b: T): T"><wbr />bar<span class="attachedType" style="visibility:hidden"></span></a></li>
 
   </ul>
@@ -1263,7 +1263,7 @@ function main() {
 <li>
   <a class="reference reference-toplevel" href="#17" id="67">Macros</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#bar.m,"
+      <li><a class="reference" href="#bar.m%2C"
     title="bar(): untyped"><wbr />bar<span class="attachedType" style="visibility:hidden"></span></a></li>
 
   </ul>
@@ -1271,7 +1271,7 @@ function main() {
 <li>
   <a class="reference reference-toplevel" href="#18" id="68">Templates</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#foo.t,SomeType,SomeType"
+      <li><a class="reference" href="#foo.t%2CSomeType%2CSomeType"
     title="foo(a, b: SomeType)"><wbr />foo<span class="attachedType" style="visibility:hidden"></span></a></li>
 
   </ul>
@@ -1297,7 +1297,8 @@ function main() {
 <div class="section" id="8">
 <h1><a class="toc-backref" href="#8">Vars</a></h1>
 <dl class="item">
-<dt id="aVariable"><a name="aVariable"></a><pre><span class="Identifier">aVariable</span><span class="Other">:</span> <span class="Identifier">array</span><span class="Other">[</span><span class="DecNumber">1</span><span class="Other">,</span> <span class="Identifier">int</span><span class="Other">]</span></pre></dt>
+<a id="aVariable"></a>
+<dt><pre><span class="Identifier">aVariable</span><span class="Other">:</span> <span class="Identifier">array</span><span class="Other">[</span><span class="DecNumber">1</span><span class="Other">,</span> <span class="Identifier">int</span><span class="Other">]</span></pre></dt>
 <dd>
 
 
@@ -1307,7 +1308,8 @@ function main() {
 <div class="section" id="12">
 <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <dl class="item">
-<dt id="bar"><a name="bar,T,T"></a><pre><span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span></pre></dt>
+<a id="bar%2CT%2CT"></a>
+<dt><pre><span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span></pre></dt>
 <dd>
 
 
@@ -1317,7 +1319,8 @@ function main() {
 <div class="section" id="17">
 <h1><a class="toc-backref" href="#17">Macros</a></h1>
 <dl class="item">
-<dt id="bar"><a name="bar.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">bar</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
+<a id="bar.m%2C"></a>
+<dt><pre><span class="Keyword">macro</span> <span class="Identifier">bar</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
 <dd>
 
 
@@ -1327,7 +1330,8 @@ function main() {
 <div class="section" id="18">
 <h1><a class="toc-backref" href="#18">Templates</a></h1>
 <dl class="item">
-<dt id="foo"><a name="foo.t,SomeType,SomeType"></a><pre><span class="Keyword">template</span> <span class="Identifier">foo</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
+<a id="foo.t%2CSomeType%2CSomeType"></a>
+<dt><pre><span class="Keyword">template</span> <span class="Identifier">foo</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
 <dd>
 This does nothing 
 
diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html
index fc5c0e1c5..106a3be1d 100644
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -1227,9 +1227,9 @@ function main() {
           </ul></dd>
 <dt><a name="bar" href="#bar"><span>bar:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
-          data-doc-search-tag="testproject: bar[T](a, b: T): T" href="testproject.html#bar,T,T">testproject: bar[T](a, b: T): T</a></li>
+          data-doc-search-tag="testproject: bar[T](a, b: T): T" href="testproject.html#bar%2CT%2CT">testproject: bar[T](a, b: T): T</a></li>
           <li><a class="reference external"
-          data-doc-search-tag="testproject: bar(): untyped" href="testproject.html#bar.m,">testproject: bar(): untyped</a></li>
+          data-doc-search-tag="testproject: bar(): untyped" href="testproject.html#bar.m%2C">testproject: bar(): untyped</a></li>
           </ul></dd>
 <dt><a name="enumValueA" href="#enumValueA"><span>enumValueA:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
@@ -1245,7 +1245,7 @@ function main() {
           </ul></dd>
 <dt><a name="foo" href="#foo"><span>foo:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
-          data-doc-search-tag="testproject: foo(a, b: SomeType)" href="testproject.html#foo.t,SomeType,SomeType">testproject: foo(a, b: SomeType)</a></li>
+          data-doc-search-tag="testproject: foo(a, b: SomeType)" href="testproject.html#foo.t%2CSomeType%2CSomeType">testproject: foo(a, b: SomeType)</a></li>
           </ul></dd>
 <dt><a name="SomeType" href="#SomeType"><span>SomeType:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
@@ -1253,7 +1253,7 @@ function main() {
           </ul></dd>
 <dt><a name="someType" href="#someType"><span>someType:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
-          data-doc-search-tag="utils: someType(): SomeType" href="subdir/subdir_b/utils.html#someType,">utils: someType(): SomeType</a></li>
+          data-doc-search-tag="utils: someType(): SomeType" href="subdir/subdir_b/utils.html#someType%2C">utils: someType(): SomeType</a></li>
           </ul></dd>
 </dl>
     <div class="row">