merged better html links #850

1 files changed, 32 insertions, 3 deletions

diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg
index 63a3c30c4..dc241db50 100644
--- a/config/nimdoc.cfg
+++ b/config/nimdoc.cfg
@@ -1,6 +1,7 @@
 # This is the config file for the documentation generator.
 # (c) 2012 Andreas Rumpf
-# Feel free to edit the templates as you need.
+# Feel free to edit the templates as you need. If you modify this file, it
+# might be worth updating the hardcoded values in packages/docutils/rstgen.ni
 
 split.item.toc = "20"  
 # too long entries in the table of contents wrap around
@@ -23,17 +24,45 @@ doc.section.toc = """
 </li>
 """
 
+# Chunk of HTML emmited for each entry in the HTML table of contents.
+# Available variables are:
+# * $desc: the actual docstring of the item.
+# * $header: the full version of name, including types, pragmas, tags, etc.
+# * $header_plain: like header but without HTML, for attribute embedding.
+# * $itemID: numerical unique entry of the item in the HTML.
+# * $itemSym: short symbolic name of the item for easier hyperlinking.
+# * $itemSymEnc: quoted version for URLs or attributes.
+# * $itemSymOrID: the symbolic name or the ID if that is not unique.
+# * $itemSymOrIDEnc: quoted version for URLs or attributes.
+# * $name: reduced name of the item.
+# * $seeSrc: generated HTML from doc.item.seesrc (if some switches are used).
+
 doc.item = """
-<dt id="$itemID"><pre>$header</pre></dt>
+<dt id="$itemSym"><a name="$itemSymOrID"></a><pre>$header</pre></dt>
 <dd>
 $desc
+$seeSrc
 </dd>
 """
 
+# Chunk of HTML emmited for each entry in the HTML table of contents.
+# See doc.item for available substitution variables.
 doc.item.toc = """
-  <li><a class="reference" href="#$itemID">$name</a></li>
+  <li><a class="reference" href="#$itemSymOrID"
+    title="$header_plain">$name</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 --docSeeSrcURL. Available
+# substitutaion variables here are:
+# * $path: relative path to the file being processed.
+# * $line: line of the item in the original source file.
+# * $url: whatever you did pass through the --docSeeSrcUrl switch (which also
+#   gets variables path/line replaced!)
+doc.item.seesrc = """<a
+href="https://github.com/Araq/Nimrod/blob/${url}/${path}#L${line}"
+>See source</a>"""
+
 doc.toc = """
 <div class="navigation" id="navigation">
 <ul class="simple">