rstgen.html 77 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677
  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <!-- This file is generated by Nim. -->
  4. <html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
  5. <head>
  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  7. <meta name="viewport" content="width=device-width, initial-scale=1.0">
  8. <title>packages/docutils/rstgen</title>
  9. <!-- Google fonts -->
  10. <link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
  11. <link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
  12. <!-- Favicon -->
  13. <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=="/>
  14. <link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
  15. <!-- CSS -->
  16. <link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
  17. <!-- JS -->
  18. <script type="text/javascript" src="dochack.js?v=2.3.1"></script>
  19. </head>
  20. <body>
  21. <div class="document" id="documentId">
  22. <div class="container">
  23. <h1 class="title">packages/docutils/rstgen</h1>
  24. <div class="row">
  25. <div class="three columns">
  26. <div class="theme-select-wrapper">
  27. <label for="theme-select">Theme:&nbsp;</label>
  28. <select id="theme-select" onchange="setTheme(this.value)">
  29. <option value="auto">🌗 Match OS</option>
  30. <option value="dark">🌑 Dark</option>
  31. <option value="light">🌕 Light</option>
  32. </select>
  33. </div>
  34. <div id="global-links">
  35. <ul class="simple-boot">
  36. <li><a href="manual.html">Manual</a></li>
  37. <li><a href="lib.html">Standard library</a></li>
  38. <li> <a id="indexLink" href="theindex.html">Index</a></li>
  39. <li><a href="compiler/theindex.html">Compiler docs</a></li>
  40. <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
  41. <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
  42. </ul>
  43. </div>
  44. <div id="searchInputDiv">
  45. Search: <input type="search" id="searchInput"
  46. oninput="search()" />
  47. </div>
  48. <ul class="simple simple-toc" id="toc-list">
  49. <li>
  50. <a class="reference reference-toplevel" href="#6" id="56">Imports</a>
  51. </li>
  52. <li>
  53. <details open>
  54. <summary><a class="reference reference-toplevel" href="#7" id="57">Types</a></summary>
  55. <ul class="simple simple-toc-section">
  56. <li><a class="reference" href="#EscapeMode" title="EscapeMode = enum
  57. emText, emOption, emUrl">EscapeMode</a></li>
  58. <li><a class="reference" href="#IndexedDocs" title="IndexedDocs = Table[IndexEntry, seq[IndexEntry]]">IndexedDocs</a></li>
  59. <li><a class="reference" href="#MetaEnum" title="MetaEnum = enum
  60. metaNone, metaTitleRaw, metaTitle, metaSubtitle, metaAuthor, metaVersion">MetaEnum</a></li>
  61. <li><a class="reference" href="#OutputTarget" title="OutputTarget = enum
  62. outHtml, outLatex">OutputTarget</a></li>
  63. <li><a class="reference" href="#RstGenerator" title="RstGenerator = object of RootObj
  64. target*: OutputTarget
  65. config*: StringTableRef
  66. splitAfter*: int
  67. listingCounter*: int
  68. tocPart*: seq[PRstNode]
  69. hasToc*: bool
  70. findFile*: FindFileHandler
  71. msgHandler*: MsgHandler
  72. outDir*: string ## output directory, initialized by docgen.nim
  73. destFile*: string ## output (HTML) file, initialized by docgen.nim
  74. filenames*: RstFileTable
  75. filename*: string ## source Nim or Rst file
  76. meta*: array[MetaEnum, string]
  77. ## \
  78. ## Stores the empty string or the last headline/overline found in the rst
  79. ## document, so it can be used as a prettier name for term index generation.
  80. ## \
  81. ## Keeps count of same text index terms to generate different identifiers
  82. ## for hyperlinks. See renderIndexTerm proc for details.
  83. id*: int ## A counter useful for generating IDs.
  84. onTestSnippet*: proc (d: var RstGenerator; filename, cmd: string; status: int;
  85. content: string) {.gcsafe.}
  86. escMode*: EscapeMode">RstGenerator</a></li>
  87. </ul>
  88. </details>
  89. </li>
  90. <li>
  91. <details open>
  92. <summary><a class="reference reference-toplevel" href="#10" id="60">Consts</a></summary>
  93. <ul class="simple simple-toc-section">
  94. <li><a class="reference" href="#IndexExt" title="IndexExt = &quot;.idx&quot;">IndexExt</a></li>
  95. </ul>
  96. </details>
  97. </li>
  98. <li>
  99. <details open>
  100. <summary><a class="reference reference-toplevel" href="#12" id="62">Procs</a></summary>
  101. <ul class="simple simple-toc-section">
  102. <ul class="simple nested-toc-section">defaultConfig
  103. <li><a class="reference" href="#defaultConfig" title="defaultConfig(): StringTableRef">defaultConfig(): StringTableRef</a></li>
  104. </ul>
  105. <ul class="simple nested-toc-section">esc
  106. <li><a class="reference" href="#esc%2COutputTarget%2Cstring%2Cint" title="esc(target: OutputTarget; s: string; splitAfter = -1; escMode = emText): string">esc(target: OutputTarget; s: string; splitAfter = -1; escMode = emText): string</a></li>
  107. </ul>
  108. <ul class="simple nested-toc-section">escChar
  109. <li><a class="reference" href="#escChar%2COutputTarget%2Cstring%2Cchar%2CEscapeMode" title="escChar(target: OutputTarget; dest: var string; c: char; escMode: EscapeMode)">escChar(target: OutputTarget; dest: var string; c: char; escMode: EscapeMode)</a></li>
  110. </ul>
  111. <ul class="simple nested-toc-section">formatNamedVars
  112. <li><a class="reference" href="#formatNamedVars%2Cstring%2CopenArray%5Bstring%5D%2CopenArray%5Bstring%5D" title="formatNamedVars(frmt: string; varnames: openArray[string];
  113. varvalues: openArray[string]): string">formatNamedVars(frmt: string; varnames: openArray[string];
  114. varvalues: openArray[string]): string</a></li>
  115. </ul>
  116. <ul class="simple nested-toc-section">initRstGenerator
  117. <li><a class="reference" href="#initRstGenerator%2CRstGenerator%2COutputTarget%2CStringTableRef%2Cstring%2CFindFileHandler%2CMsgHandler" title="initRstGenerator(g: var RstGenerator; target: OutputTarget;
  118. config: StringTableRef; filename: string;
  119. findFile: FindFileHandler = nil; msgHandler: MsgHandler = nil;
  120. filenames = default(RstFileTable); hasToc = false)">initRstGenerator(g: var RstGenerator; target: OutputTarget;
  121. config: StringTableRef; filename: string;
  122. findFile: FindFileHandler = nil; msgHandler: MsgHandler = nil;
  123. filenames = default(RstFileTable); hasToc = false)</a></li>
  124. </ul>
  125. <ul class="simple nested-toc-section">mergeIndexes
  126. <li><a class="reference" href="#mergeIndexes%2Cstring" title="mergeIndexes(dir: string): string">mergeIndexes(dir: string): string</a></li>
  127. </ul>
  128. <ul class="simple nested-toc-section">nextSplitPoint
  129. <li><a class="reference" href="#nextSplitPoint%2Cstring%2Cint" title="nextSplitPoint(s: string; start: int): int">nextSplitPoint(s: string; start: int): int</a></li>
  130. </ul>
  131. <ul class="simple nested-toc-section">prettyLink
  132. <li><a class="reference" href="#prettyLink%2Cstring" title="prettyLink(file: string): string">prettyLink(file: string): string</a></li>
  133. </ul>
  134. <ul class="simple nested-toc-section">readIndexDir
  135. <li><a class="reference" href="#readIndexDir%2Cstring" title="readIndexDir(dir: string): tuple[modules: seq[string], symbols: seq[IndexEntry],
  136. docs: IndexedDocs]">readIndexDir(dir: string): tuple[modules: seq[string], symbols: seq[IndexEntry],
  137. docs: IndexedDocs]</a></li>
  138. </ul>
  139. <ul class="simple nested-toc-section">renderCodeLang
  140. <li><a class="reference" href="#renderCodeLang%2Cstring%2CSourceLanguage%2Cstring%2COutputTarget" title="renderCodeLang(result: var string; lang: SourceLanguage; code: string;
  141. target: OutputTarget)">renderCodeLang(result: var string; lang: SourceLanguage; code: string;
  142. target: OutputTarget)</a></li>
  143. </ul>
  144. <ul class="simple nested-toc-section">renderIndexTerm
  145. <li><a class="reference" href="#renderIndexTerm%2CPDoc%2CPRstNode%2Cstring" title="renderIndexTerm(d: PDoc; n: PRstNode; result: var string)">renderIndexTerm(d: PDoc; n: PRstNode; result: var string)</a></li>
  146. </ul>
  147. <ul class="simple nested-toc-section">renderNimCode
  148. <li><a class="reference" href="#renderNimCode%2Cstring%2Cstring%2COutputTarget" title="renderNimCode(result: var string; code: string; target: OutputTarget)">renderNimCode(result: var string; code: string; target: OutputTarget)</a></li>
  149. </ul>
  150. <ul class="simple nested-toc-section">renderRstToOut
  151. <li><a class="reference" href="#renderRstToOut%2CRstGenerator%2CPRstNode%2Cstring" title="renderRstToOut(d: var RstGenerator; n: PRstNode; result: var string)">renderRstToOut(d: var RstGenerator; n: PRstNode; result: var string)</a></li>
  152. </ul>
  153. <ul class="simple nested-toc-section">renderTocEntries
  154. <li><a class="reference" href="#renderTocEntries%2CRstGenerator%2Cint%2Cint%2Cstring" title="renderTocEntries(d: var RstGenerator; j: var int; lvl: int; result: var string)">renderTocEntries(d: var RstGenerator; j: var int; lvl: int; result: var string)</a></li>
  155. </ul>
  156. <ul class="simple nested-toc-section">rstToHtml
  157. <li><a class="reference" href="#rstToHtml%2Cstring%2CRstParseOptions%2CStringTableRef%2CMsgHandler" title="rstToHtml(s: string; options: RstParseOptions; config: StringTableRef;
  158. msgHandler: MsgHandler = rst.defaultMsgHandler): string">rstToHtml(s: string; options: RstParseOptions; config: StringTableRef;
  159. msgHandler: MsgHandler = rst.defaultMsgHandler): string</a></li>
  160. </ul>
  161. <ul class="simple nested-toc-section">rstToLatex
  162. <li><a class="reference" href="#rstToLatex%2Cstring%2CRstParseOptions" title="rstToLatex(rstSource: string; options: RstParseOptions): string">rstToLatex(rstSource: string; options: RstParseOptions): string</a></li>
  163. </ul>
  164. <ul class="simple nested-toc-section">setIndexTerm
  165. <li><a class="reference" href="#setIndexTerm%2CRstGenerator%2CIndexEntryKind%2Cstring%2Cstring%2Cstring%2Cstring%2Cstring%2Cint" title="setIndexTerm(d: var RstGenerator; k: IndexEntryKind; htmlFile, id, term: string;
  166. linkTitle, linkDesc = &quot;&quot;; line = 0)">setIndexTerm(d: var RstGenerator; k: IndexEntryKind; htmlFile, id, term: string;
  167. linkTitle, linkDesc = &quot;&quot;; line = 0)</a></li>
  168. </ul>
  169. <ul class="simple nested-toc-section">traverseForIndex
  170. <li><a class="reference" href="#traverseForIndex%2CPDoc%2CPRstNode" title="traverseForIndex(d: PDoc; n: PRstNode)">traverseForIndex(d: PDoc; n: PRstNode)</a></li>
  171. </ul>
  172. <ul class="simple nested-toc-section">writeIndexFile
  173. <li><a class="reference" href="#writeIndexFile%2CRstGenerator%2Cstring" title="writeIndexFile(g: var RstGenerator; outfile: string)">writeIndexFile(g: var RstGenerator; outfile: string)</a></li>
  174. </ul>
  175. </ul>
  176. </details>
  177. </li>
  178. </ul>
  179. </div>
  180. <div class="nine columns" id="content">
  181. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  182. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  183. <div id="tocRoot"></div>
  184. <p class="module-desc"><p>This module implements a generator of HTML/Latex from <span id="restructuredtext_1">reStructuredText</span> (see <a class="reference external" href="https://docutils.sourceforge.net/rst.html">https://docutils.sourceforge.net/rst.html</a> for information on this markup syntax) and is used by the compiler's <a class="reference external" href="docgen.html">docgen tools</a>.</p>
  185. <p>You can generate HTML output through the convenience proc <tt class="docutils literal"><span class="pre">rstToHtml</span></tt>, which provided an input string with rst markup returns a string with the generated HTML. The final output is meant to be embedded inside a full document you provide yourself, so it won't contain the usual <tt class="docutils literal"><span class="pre">&lt;header&gt;</span></tt> or <tt class="docutils literal"><span class="pre">&lt;body&gt;</span></tt> parts.</p>
  186. <p>You can also create a <tt class="docutils literal"><span class="pre">RstGenerator</span></tt> structure and populate it with the other lower level methods to finally build complete documents. This requires many options and tweaking, but you are not limited to snippets and can generate <a class="reference external" href="https://en.wikipedia.org/wiki/LaTeX">LaTeX documents</a> too.</p>
  187. <p><a class="reference external" href="https://docutils.sourceforge.io/docs/user/config.htm">Docutils configuration files</a> are not supported. Instead HTML generation can be tweaked by editing file <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt>.</p>
  188. <p>There are stylistic difference between how this module renders some elements and how original Python Docutils does:</p>
  189. <ul class="simple"><li>Backreferences to TOC in section headings are not generated. In HTML each section is also a link that points to the section itself: this is done for user to be able to copy the link into clipboard.</li>
  190. <li>The same goes for footnotes/citations links: they point to themselves. No backreferences are generated since finding all references of a footnote can be done by simply searching for <tt class="docutils literal"><span class="pre">[footnoteName]</span></tt>.</li>
  191. </ul>
  192. </p>
  193. <div class="section" id="6">
  194. <h1><a class="toc-backref" href="#6">Imports</a></h1>
  195. <dl class="item">
  196. <a class="reference external" href="strutils.html">strutils</a>, <a class="reference external" href="os.html">os</a>, <a class="reference external" href="hashes.html">hashes</a>, <a class="reference external" href="strtabs.html">strtabs</a>, <a class="reference external" href="tables.html">tables</a>, <a class="reference external" href="sequtils.html">sequtils</a>, <a class="reference external" href="algorithm.html">algorithm</a>, <a class="reference external" href="parseutils.html">parseutils</a>, <a class="reference external" href="strbasics.html">strbasics</a>, <a class="reference external" href="rstast.html">rstast</a>, <a class="reference external" href="rst.html">rst</a>, <a class="reference external" href="rstidx.html">rstidx</a>, <a class="reference external" href="highlite.html">highlite</a>, <a class="reference external" href="assertions.html">assertions</a>, <a class="reference external" href="syncio.html">syncio</a>, <a class="reference external" href="formatfloat.html">formatfloat</a>, <a class="reference external" href="since.html">since</a>
  197. </dl>
  198. </div>
  199. <div class="section" id="7">
  200. <h1><a class="toc-backref" href="#7">Types</a></h1>
  201. <dl class="item">
  202. <div id="EscapeMode">
  203. <dt><pre><a href="rstgen.html#EscapeMode"><span class="Identifier">EscapeMode</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
  204. <span class="Identifier">emText</span><span class="Other">,</span> <span class="Identifier">emOption</span><span class="Other">,</span> <span class="Identifier">emUrl</span></pre></dt>
  205. <dd>
  206. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L65" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  207. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L65" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  208. </dd>
  209. </div>
  210. <div id="IndexedDocs">
  211. <dt><pre><a href="rstgen.html#IndexedDocs"><span class="Identifier">IndexedDocs</span></a> <span class="Other">=</span> <a href="tables.html#Table"><span class="Identifier">Table</span></a><span class="Other">[</span><a href="rstidx.html#IndexEntry"><span class="Identifier">IndexEntry</span></a><span class="Other">,</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="rstidx.html#IndexEntry"><span class="Identifier">IndexEntry</span></a><span class="Other">]</span><span class="Other">]</span></pre></dt>
  212. <dd>
  213. <p>
  214. Contains the index sequences for doc types.</p>
  215. <p>The key is a <em>fake</em> IndexEntry which will contain the title of the document in the <tt class="docutils literal"><span class="pre"><span class="Identifier">keyword</span></span></tt> field and <tt class="docutils literal"><span class="pre"><span class="Identifier">link</span></span></tt> will contain the html filename for the document. <tt class="docutils literal"><span class="pre"><span class="Identifier">linkTitle</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">linkDesc</span></span></tt> will be empty.</p>
  216. <p>The value indexed by this IndexEntry is a sequence with the real index entries found in the <tt class="docutils literal"><span class="pre">.idx</span></tt> file.</p>
  217. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L394" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  218. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L394" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  219. </dd>
  220. </div>
  221. <div id="MetaEnum">
  222. <dt><pre><a href="rstgen.html#MetaEnum"><span class="Identifier">MetaEnum</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
  223. <span class="Identifier">metaNone</span><span class="Other">,</span> <span class="Identifier">metaTitleRaw</span><span class="Other">,</span> <span class="Identifier">metaTitle</span><span class="Other">,</span> <span class="Identifier">metaSubtitle</span><span class="Other">,</span> <span class="Identifier">metaAuthor</span><span class="Other">,</span> <span class="Identifier">metaVersion</span></pre></dt>
  224. <dd>
  225. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L62" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  226. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L62" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  227. </dd>
  228. </div>
  229. <div id="OutputTarget">
  230. <dt><pre><a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
  231. <span class="Identifier">outHtml</span><span class="Other">,</span> <span class="Identifier">outLatex</span></pre></dt>
  232. <dd>
  233. which document type to generate
  234. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L58" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  235. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L58" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  236. </dd>
  237. </div>
  238. <div id="RstGenerator">
  239. <dt><pre><a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a> <span class="Other">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <a href="system.html#RootObj"><span class="Identifier">RootObj</span></a>
  240. <span class="Identifier">target</span><span class="Operator">*</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a>
  241. <span class="Identifier">config</span><span class="Operator">*</span><span class="Other">:</span> <a href="strtabs.html#StringTableRef"><span class="Identifier">StringTableRef</span></a>
  242. <span class="Identifier">splitAfter</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a>
  243. <span class="Identifier">listingCounter</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a>
  244. <span class="Identifier">tocPart</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="rstast.html#PRstNode"><span class="Identifier">PRstNode</span></a><span class="Other">]</span>
  245. <span class="Identifier">hasToc</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#bool"><span class="Identifier">bool</span></a>
  246. <span class="Identifier">findFile</span><span class="Operator">*</span><span class="Other">:</span> <a href="rst.html#FindFileHandler"><span class="Identifier">FindFileHandler</span></a>
  247. <span class="Identifier">msgHandler</span><span class="Operator">*</span><span class="Other">:</span> <a href="rst.html#MsgHandler"><span class="Identifier">MsgHandler</span></a>
  248. <span class="Identifier">outDir</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> <span class="Comment">## output directory, initialized by docgen.nim</span>
  249. <span class="Identifier">destFile</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> <span class="Comment">## output (HTML) file, initialized by docgen.nim</span>
  250. <span class="Identifier">filenames</span><span class="Operator">*</span><span class="Other">:</span> <a href="rst.html#RstFileTable"><span class="Identifier">RstFileTable</span></a>
  251. <span class="Identifier">filename</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> <span class="Comment">## source Nim or Rst file</span>
  252. <span class="Identifier">meta</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#array"><span class="Identifier">array</span></a><span class="Other">[</span><span class="Identifier">MetaEnum</span><span class="Other">,</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span>
  253. <span class="Comment">## \</span>
  254. <span class="Comment">## Stores the empty string or the last headline/overline found in the rst</span>
  255. <span class="Comment">## document, so it can be used as a prettier name for term index generation.</span>
  256. <span class="Comment">## \</span>
  257. <span class="Comment">## Keeps count of same text index terms to generate different identifiers</span>
  258. <span class="Comment">## for hyperlinks. See renderIndexTerm proc for details.</span>
  259. <span class="Identifier">id</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a> <span class="Comment">## A counter useful for generating IDs.</span>
  260. <span class="Identifier">onTestSnippet</span><span class="Operator">*</span><span class="Other">:</span> <span class="Keyword">proc</span> <span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">filename</span><span class="Other">,</span> <span class="Identifier">cmd</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">status</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a><span class="Other">;</span>
  261. <span class="Identifier">content</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span></span>.}
  262. <span class="Identifier">escMode</span><span class="Operator">*</span><span class="Other">:</span> <a href="rstgen.html#EscapeMode"><span class="Identifier">EscapeMode</span></a></pre></dt>
  263. <dd>
  264. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L69" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  265. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L69" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  266. </dd>
  267. </div>
  268. </dl>
  269. </div>
  270. <div class="section" id="10">
  271. <h1><a class="toc-backref" href="#10">Consts</a></h1>
  272. <dl class="item">
  273. <div id="IndexExt">
  274. <dt><pre><a href="rstgen.html#IndexExt"><span class="Identifier">IndexExt</span></a> <span class="Other">=</span> <span class="StringLit">&quot;.idx&quot;</span></pre></dt>
  275. <dd>
  276. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L55" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  277. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L55" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  278. </dd>
  279. </div>
  280. </dl>
  281. </div>
  282. <div class="section" id="12">
  283. <h1><a class="toc-backref" href="#12">Procs</a></h1>
  284. <dl class="item">
  285. <div id="defaultConfig-procs-all">
  286. <div id="defaultConfig">
  287. <dt><pre><span class="Keyword">proc</span> <a href="#defaultConfig"><span class="Identifier">defaultConfig</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="strtabs.html#StringTableRef"><span class="Identifier">StringTableRef</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  288. <dd>
  289. <p>Returns a default configuration for embedded HTML generation.</p>
  290. <p>The returned <tt class="docutils literal"><span class="pre">StringTableRef</span></tt> contains the parameters used by the HTML engine to build the final output. For information on what these parameters are and their purpose, please look up the file <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt> bundled with the compiler.</p>
  291. <p>The only difference between the contents of that file and the values provided by this proc is the <tt class="docutils literal"><span class="pre">doc.file</span></tt> variable. The <tt class="docutils literal"><span class="pre">doc.file</span></tt> variable of the configuration file contains HTML to build standalone pages, while this proc returns just the content for procs like <tt class="docutils literal"><span class="pre">rstToHtml</span></tt> to generate the bare minimum HTML.</p>
  292. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1445" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  293. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1445" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  294. </dd>
  295. </div>
  296. </div>
  297. <div id="esc-procs-all">
  298. <div id="esc,OutputTarget,string,int">
  299. <dt><pre><span class="Keyword">proc</span> <a href="#esc%2COutputTarget%2Cstring%2Cint"><span class="Identifier">esc</span></a><span class="Other">(</span><span class="Identifier">target</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a><span class="Other">;</span> <span class="Identifier">s</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">splitAfter</span> <span class="Other">=</span> <span class="DecNumber">-1</span><span class="Other">;</span> <span class="Identifier">escMode</span> <span class="Other">=</span> <span class="Identifier">emText</span><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.
  300. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  301. <dd>
  302. Escapes the HTML.
  303. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L252" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  304. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L252" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  305. </dd>
  306. </div>
  307. </div>
  308. <div id="escChar-procs-all">
  309. <div id="escChar,OutputTarget,string,char,EscapeMode">
  310. <dt><pre><span class="Keyword">proc</span> <a href="#escChar%2COutputTarget%2Cstring%2Cchar%2CEscapeMode"><span class="Identifier">escChar</span></a><span class="Other">(</span><span class="Identifier">target</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a><span class="Other">;</span> <span class="Identifier">dest</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">c</span><span class="Other">:</span> <a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">;</span>
  311. <span class="Identifier">escMode</span><span class="Other">:</span> <a href="rstgen.html#EscapeMode"><span class="Identifier">EscapeMode</span></a><span class="Other">)</span> {.<span class="Identifier">inline</span><span class="Other">,</span> <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  312. <dd>
  313. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L229" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  314. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L229" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  315. </dd>
  316. </div>
  317. </div>
  318. <div id="formatNamedVars-procs-all">
  319. <div id="formatNamedVars,string,openArray[string],openArray[string]">
  320. <dt><pre><span class="Keyword">proc</span> <a href="#formatNamedVars%2Cstring%2CopenArray%5Bstring%5D%2CopenArray%5Bstring%5D"><span class="Identifier">formatNamedVars</span></a><span class="Other">(</span><span class="Identifier">frmt</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">varnames</span><span class="Other">:</span> <a href="system.html#openArray"><span class="Identifier">openArray</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span><span class="Other">;</span>
  321. <span class="Identifier">varvalues</span><span class="Other">:</span> <a href="system.html#openArray"><span class="Identifier">openArray</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.
  322. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ValueError</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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  323. <dd>
  324. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1384" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  325. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1384" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  326. </dd>
  327. </div>
  328. </div>
  329. <div id="initRstGenerator-procs-all">
  330. <div id="initRstGenerator,RstGenerator,OutputTarget,StringTableRef,string,FindFileHandler,MsgHandler">
  331. <dt><pre><span class="Keyword">proc</span> <a href="#initRstGenerator%2CRstGenerator%2COutputTarget%2CStringTableRef%2Cstring%2CFindFileHandler%2CMsgHandler"><span class="Identifier">initRstGenerator</span></a><span class="Other">(</span><span class="Identifier">g</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">target</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a><span class="Other">;</span>
  332. <span class="Identifier">config</span><span class="Other">:</span> <a href="strtabs.html#StringTableRef"><span class="Identifier">StringTableRef</span></a><span class="Other">;</span> <span class="Identifier">filename</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span>
  333. <span class="Identifier">findFile</span><span class="Other">:</span> <a href="rst.html#FindFileHandler"><span class="Identifier">FindFileHandler</span></a> <span class="Other">=</span> <span class="Keyword">nil</span><span class="Other">;</span>
  334. <span class="Identifier">msgHandler</span><span class="Other">:</span> <a href="rst.html#MsgHandler"><span class="Identifier">MsgHandler</span></a> <span class="Other">=</span> <span class="Keyword">nil</span><span class="Other">;</span>
  335. <span class="Identifier">filenames</span> <span class="Other">=</span> <span class="Identifier">default</span><span class="Other">(</span><a href="rst.html#RstFileTable"><span class="Identifier">RstFileTable</span></a><span class="Other">)</span><span class="Other">;</span> <span class="Identifier">hasToc</span> <span class="Other">=</span> <span class="Identifier">false</span><span class="Other">)</span> {.
  336. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ValueError</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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  337. <dd>
  338. <p>Initializes a <tt class="docutils literal"><span class="pre">RstGenerator</span></tt>.</p>
  339. <p>You need to call this before using a <tt class="docutils literal"><span class="pre">RstGenerator</span></tt> with any other procs in this module. Pass a non <tt class="docutils literal"><span class="pre">nil</span></tt> <tt class="docutils literal"><span class="pre">StringTableRef</span></tt> value as <tt class="docutils literal"><span class="pre"><span class="Identifier">config</span></span></tt> with parameters used by the HTML output generator. If you don't know what to use, pass the results of the <tt class="docutils literal"><span class="pre"><span class="Identifier">defaultConfig</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">&lt;</span><span class="Comment">#defaultConfig&gt;_</span></span></tt> proc.</p>
  340. <p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">filename</span></span></tt> parameter will be used for error reporting and creating index hyperlinks to the file, but you can pass an empty string here if you are parsing a stream in memory. If <tt class="docutils literal"><span class="pre"><span class="Identifier">filename</span></span></tt> ends with the <tt class="docutils literal"><span class="pre">.nim</span></tt> extension, the title for the document will be set by default to <tt class="docutils literal"><span class="pre">Module filename</span></tt>. This default title can be overridden by the embedded rst, but it helps to prettify the generated index if no title is found.</p>
  341. <p>The <tt class="docutils literal"><span class="pre">RstParseOptions</span></tt>, <tt class="docutils literal"><span class="pre">FindFileHandler</span></tt> and <tt class="docutils literal"><span class="pre">MsgHandler</span></tt> types are defined in the <a class="reference external" href="rst.html">packages/docutils/rst module</a>. <tt class="docutils literal"><span class="pre">options</span></tt> selects the behaviour of the rst parser.</p>
  342. <p><tt class="docutils literal"><span class="pre">findFile</span></tt> is a proc used by the rst <tt class="docutils literal"><span class="pre">include</span></tt> directive among others. The purpose of this proc is to mangle or filter paths. It receives paths specified in the rst document and has to return a valid path to existing files or the empty string otherwise. If you pass <tt class="docutils literal"><span class="pre">nil</span></tt>, a default proc will be used which given a path returns the input path only if the file exists. One use for this proc is to transform relative paths found in the document to absolute path, useful if the rst file and the resources it references are not in the same directory as the current working directory.</p>
  343. <p>The <tt class="docutils literal"><span class="pre">msgHandler</span></tt> is a proc used for user error reporting. It will be called with the filename, line, col, and type of any error found during parsing. If you pass <tt class="docutils literal"><span class="pre">nil</span></tt>, a default message handler will be used which writes the messages to the standard output.</p>
  344. <p>Example:</p>
  345. <p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">packages</span><span class="Operator">/</span><span class="Identifier">docutils</span><span class="Operator">/</span><span class="Identifier">rstgen</span>
  346. <span class="Keyword">var</span> <span class="Identifier">gen</span><span class="Punctuation">:</span> <span class="Identifier">RstGenerator</span>
  347. <span class="Identifier">gen</span><span class="Operator">.</span><span class="Identifier">initRstGenerator</span><span class="Punctuation">(</span><span class="Identifier">outHtml</span><span class="Punctuation">,</span> <span class="Identifier">defaultConfig</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="StringLit">&quot;filename&quot;</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">}</span><span class="Punctuation">)</span></pre></p>
  348. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L116" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  349. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L116" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  350. </dd>
  351. </div>
  352. </div>
  353. <div id="mergeIndexes-procs-all">
  354. <div id="mergeIndexes,string">
  355. <dt><pre><span class="Keyword">proc</span> <a href="#mergeIndexes%2Cstring"><span class="Identifier">mergeIndexes</span></a><span class="Other">(</span><span class="Identifier">dir</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">OSError</span><span class="Other">,</span> <span class="Identifier">IOError</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span>
  356. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadDirEffect</span><span class="Other">,</span> <span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  357. <dd>
  358. <p>Merges all index files in <tt class="docutils literal"><span class="pre"><span class="Identifier">dir</span></span></tt> and returns the generated index as HTML.</p>
  359. <p>This proc will first scan <tt class="docutils literal"><span class="pre"><span class="Identifier">dir</span></span></tt> for index files with the <tt class="docutils literal"><span class="pre">.idx</span></tt> extension previously created by commands like <tt class="docutils literal"><span class="pre">nim doc|rst2html</span></tt> which use the <tt class="docutils literal"><span class="pre">--index:on</span></tt> switch. These index files are the result of calls to <a class="reference external" href="#setIndexTerm,RstGenerator,string,string,string,string,string">setIndexTerm()</a> and <a class="reference external" href="#writeIndexFile,RstGenerator,string">writeIndexFile()</a>, so they are simple tab separated files.</p>
  360. <p>As convention this proc will split index files into two categories: documentation and API. API indices will be all joined together into a single big sorted index, making the bulk of the final index. This is good for API documentation because many symbols are repeated in different modules. On the other hand, documentation indices are essentially table of contents plus a few special markers. These documents will be rendered in a separate section which tries to maintain the order and hierarchy of the symbols in the index file.</p>
  361. <p>To differentiate between a documentation and API file a convention is used: indices which contain one entry without the HTML hash character (#) will be considered <tt class="docutils literal"><span class="pre"><span class="Identifier">documentation</span></span></tt>, since this hash-less entry is the explicit title of the document. Indices without this explicit entry will be considered <tt class="docutils literal"><span class="pre"><span class="Identifier">generated</span> <span class="Identifier">API</span></span></tt> extracted out of a source <tt class="docutils literal"><span class="pre">.nim</span></tt> file.</p>
  362. <p>Returns the merged and sorted indices into a single HTML block which can be further embedded into nimdoc templates.</p>
  363. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L624" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  364. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L624" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  365. </dd>
  366. </div>
  367. </div>
  368. <div id="nextSplitPoint-procs-all">
  369. <div id="nextSplitPoint,string,int">
  370. <dt><pre><span class="Keyword">proc</span> <a href="#nextSplitPoint%2Cstring%2Cint"><span class="Identifier">nextSplitPoint</span></a><span class="Other">(</span><span class="Identifier">s</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">start</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span>
  371. <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  372. <dd>
  373. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L240" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  374. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L240" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  375. </dd>
  376. </div>
  377. </div>
  378. <div id="prettyLink-procs-all">
  379. <div id="prettyLink,string">
  380. <dt><pre><span class="Keyword">proc</span> <a href="#prettyLink%2Cstring"><span class="Identifier">prettyLink</span></a><span class="Other">(</span><span class="Identifier">file</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  381. <dd>
  382. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L107" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  383. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L107" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  384. </dd>
  385. </div>
  386. </div>
  387. <div id="readIndexDir-procs-all">
  388. <div id="readIndexDir,string">
  389. <dt><pre><span class="Keyword">proc</span> <a href="#readIndexDir%2Cstring"><span class="Identifier">readIndexDir</span></a><span class="Other">(</span><span class="Identifier">dir</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Keyword">tuple</span><span class="Other">[</span><span class="Identifier">modules</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span><span class="Other">,</span>
  390. <span class="Identifier">symbols</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="rstidx.html#IndexEntry"><span class="Identifier">IndexEntry</span></a><span class="Other">]</span><span class="Other">,</span>
  391. <span class="Identifier">docs</span><span class="Other">:</span> <a href="rstgen.html#IndexedDocs"><span class="Identifier">IndexedDocs</span></a><span class="Other">]</span> {.
  392. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">OSError</span><span class="Other">,</span> <span class="Identifier">IOError</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadDirEffect</span><span class="Other">,</span> <span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span>
  393. <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  394. <dd>
  395. <p>Walks <tt class="docutils literal"><span class="pre"><span class="Identifier">dir</span></span></tt> reading <tt class="docutils literal"><span class="pre">.idx</span></tt> files converting them in IndexEntry items.</p>
  396. <p>Returns the list of found module names, the list of free symbol entries and the different documentation indexes. The list of modules is sorted. See the documentation of <tt class="docutils literal"><span class="pre">mergeIndexes</span></tt> for details.</p>
  397. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L577" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  398. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L577" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  399. </dd>
  400. </div>
  401. </div>
  402. <div id="renderCodeLang-procs-all">
  403. <div id="renderCodeLang,string,SourceLanguage,string,OutputTarget">
  404. <dt><pre><span class="Keyword">proc</span> <a href="#renderCodeLang%2Cstring%2CSourceLanguage%2Cstring%2COutputTarget"><span class="Identifier">renderCodeLang</span></a><span class="Other">(</span><span class="Identifier">result</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">lang</span><span class="Other">:</span> <a href="highlite.html#SourceLanguage"><span class="Identifier">SourceLanguage</span></a><span class="Other">;</span> <span class="Identifier">code</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span>
  405. <span class="Identifier">target</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ValueError</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 class="Other">,</span>
  406. <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  407. <dd>
  408. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L919" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  409. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L919" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  410. </dd>
  411. </div>
  412. </div>
  413. <div id="renderIndexTerm-procs-all">
  414. <div id="renderIndexTerm,PDoc,PRstNode,string">
  415. <dt><pre><span class="Keyword">proc</span> <a href="#renderIndexTerm%2CPDoc%2CPRstNode%2Cstring"><span class="Identifier">renderIndexTerm</span></a><span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Identifier">PDoc</span><span class="Other">;</span> <span class="Identifier">n</span><span class="Other">:</span> <a href="rstast.html#PRstNode"><span class="Identifier">PRstNode</span></a><span class="Other">;</span> <span class="Identifier">result</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span> {.
  416. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  417. <dd>
  418. <p>Renders the string decorated within `foobar`:idx: markers.</p>
  419. <p>Additionally adds the enclosed text to the index as a term. Since we are interested in different instances of the same term to have different entries, a table is used to keep track of the amount of times a term has previously appeared to give a different identifier value for each.</p>
  420. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L372" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  421. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L372" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  422. </dd>
  423. </div>
  424. </div>
  425. <div id="renderNimCode-procs-all">
  426. <div id="renderNimCode,string,string,OutputTarget">
  427. <dt><pre><span class="Keyword">proc</span> <a href="#renderNimCode%2Cstring%2Cstring%2COutputTarget"><span class="Identifier">renderNimCode</span></a><span class="Other">(</span><span class="Identifier">result</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">code</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">target</span><span class="Other">:</span> <a href="rstgen.html#OutputTarget"><span class="Identifier">OutputTarget</span></a><span class="Other">)</span> {.
  428. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ValueError</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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  429. <dd>
  430. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L935" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  431. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L935" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  432. </dd>
  433. </div>
  434. </div>
  435. <div id="renderRstToOut-procs-all">
  436. <div id="renderRstToOut,RstGenerator,PRstNode,string">
  437. <dt><pre><span class="Keyword">proc</span> <a href="#renderRstToOut%2CRstGenerator%2CPRstNode%2Cstring"><span class="Identifier">renderRstToOut</span></a><span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">n</span><span class="Other">:</span> <a href="rstast.html#PRstNode"><span class="Identifier">PRstNode</span></a><span class="Other">;</span> <span class="Identifier">result</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span> {.
  438. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  439. <dd>
  440. <p>Writes into <tt class="docutils literal"><span class="pre">result</span></tt> the rst ast <tt class="docutils literal"><span class="pre">n</span></tt> using the <tt class="docutils literal"><span class="pre">d</span></tt> configuration.</p>
  441. <p>Before using this proc you need to initialise a <tt class="docutils literal"><span class="pre">RstGenerator</span></tt> with <tt class="docutils literal"><span class="pre">initRstGenerator</span></tt> and parse a rst file with <tt class="docutils literal"><span class="pre">rstParse</span></tt> from the <a class="reference external" href="rst.html">packages/docutils/rst module</a>. Example:</p>
  442. <p><pre class="listing"><span class="Comment"># ...configure gen and rst vars...</span>
  443. <span class="Keyword">var</span> <span class="Identifier">generatedHtml</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span>
  444. <span class="Identifier">renderRstToOut</span><span class="Punctuation">(</span><span class="Identifier">gen</span><span class="Punctuation">,</span> <span class="Identifier">rst</span><span class="Punctuation">,</span> <span class="Identifier">generatedHtml</span><span class="Punctuation">)</span>
  445. <span class="Identifier">echo</span> <span class="Identifier">generatedHtml</span></pre></p>
  446. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L287" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  447. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L287" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  448. </dd>
  449. </div>
  450. </div>
  451. <div id="renderTocEntries-procs-all">
  452. <div id="renderTocEntries,RstGenerator,int,int,string">
  453. <dt><pre><span class="Keyword">proc</span> <a href="#renderTocEntries%2CRstGenerator%2Cint%2Cint%2Cstring"><span class="Identifier">renderTocEntries</span></a><span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">j</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#int"><span class="Identifier">int</span></a><span class="Other">;</span> <span class="Identifier">lvl</span><span class="Other">:</span> <a href="system.html#int"><span class="Identifier">int</span></a><span class="Other">;</span>
  454. <span class="Identifier">result</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span>
  455. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  456. <dd>
  457. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L732" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  458. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L732" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  459. </dd>
  460. </div>
  461. </div>
  462. <div id="rstToHtml-procs-all">
  463. <div id="rstToHtml,string,RstParseOptions,StringTableRef,MsgHandler">
  464. <dt><pre><span class="Keyword">proc</span> <a href="#rstToHtml%2Cstring%2CRstParseOptions%2CStringTableRef%2CMsgHandler"><span class="Identifier">rstToHtml</span></a><span class="Other">(</span><span class="Identifier">s</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">options</span><span class="Other">:</span> <a href="rst.html#RstParseOptions"><span class="Identifier">RstParseOptions</span></a><span class="Other">;</span> <span class="Identifier">config</span><span class="Other">:</span> <a href="strtabs.html#StringTableRef"><span class="Identifier">StringTableRef</span></a><span class="Other">;</span>
  465. <span class="Identifier">msgHandler</span><span class="Other">:</span> <a href="rst.html#MsgHandler"><span class="Identifier">MsgHandler</span></a> <span class="Other">=</span> <span class="Identifier">rst</span><span class="Other">.</span><span class="Identifier">defaultMsgHandler</span><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span><span class="Other">,</span>
  466. <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">,</span> <span class="Identifier">KeyError</span><span class="Other">]</span><span class="Other">,</span>
  467. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">,</span> <span class="Identifier">ReadIOEffect</span><span class="Other">,</span> <span class="Identifier">ReadEnvEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  468. <dd>
  469. <p>Converts an input rst string into embeddable HTML.</p>
  470. <p>This convenience proc parses any input string using rst markup (it doesn't have to be a full document!) and returns an embeddable piece of HTML. The proc is meant to be used in <em>online</em> environments without access to a meaningful filesystem, and therefore rst <tt class="docutils literal"><span class="pre">include</span></tt> like directives won't work. For an explanation of the <tt class="docutils literal"><span class="pre">config</span></tt> parameter see the <tt class="docutils literal"><span class="pre">initRstGenerator</span></tt> proc. Example:</p>
  471. <p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">packages</span><span class="Operator">/</span><span class="Identifier">docutils</span><span class="Operator">/</span><span class="Identifier">rstgen</span><span class="Punctuation">,</span> <span class="Identifier">strtabs</span>
  472. <span class="Identifier">echo</span> <span class="Identifier">rstToHtml</span><span class="Punctuation">(</span><span class="StringLit">&quot;*Hello* **world**!&quot;</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">}</span><span class="Punctuation">,</span>
  473. <span class="Identifier">newStringTable</span><span class="Punctuation">(</span><span class="Identifier">modeStyleInsensitive</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  474. <span class="Comment"># --&gt; &lt;em&gt;Hello&lt;/em&gt; &lt;strong&gt;world&lt;/strong&gt;!</span></pre></p>
  475. <p>If you need to allow the rst <tt class="docutils literal"><span class="pre">include</span></tt> directive or tweak the generated output you have to create your own <tt class="docutils literal"><span class="pre">RstGenerator</span></tt> with <tt class="docutils literal"><span class="pre">initRstGenerator</span></tt> and related procs.</p>
  476. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1513" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  477. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1513" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  478. </dd>
  479. </div>
  480. </div>
  481. <div id="rstToLatex-procs-all">
  482. <div id="rstToLatex,string,RstParseOptions">
  483. <dt><pre><span class="Keyword">proc</span> <a href="#rstToLatex%2Cstring%2CRstParseOptions"><span class="Identifier">rstToLatex</span></a><span class="Other">(</span><span class="Identifier">rstSource</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">options</span><span class="Other">:</span> <a href="rst.html#RstParseOptions"><span class="Identifier">RstParseOptions</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.<span class="Identifier">inline</span><span class="Other">,</span>
  484. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">,</span> <span class="Identifier">KeyError</span><span class="Other">]</span><span class="Other">,</span>
  485. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">,</span> <span class="Identifier">ReadIOEffect</span><span class="Other">,</span> <span class="Identifier">ReadEnvEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  486. <dd>
  487. Convenience proc for <tt class="docutils literal"><span class="pre"><span class="Identifier">renderRstToOut</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">initRstGenerator</span></span></tt>.
  488. <p><strong class="examples_text">Example:</strong></p>
  489. <pre class="listing"><span class="Identifier">doAssert</span> <span class="Identifier">rstToLatex</span><span class="Punctuation">(</span><span class="StringLit">&quot;*Hello* **world**&quot;</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="LongStringLit">&quot;&quot;&quot;\emph{Hello} \textbf{world}&quot;&quot;&quot;</span></pre>
  490. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1555" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  491. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1555" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  492. </dd>
  493. </div>
  494. </div>
  495. <div id="setIndexTerm-procs-all">
  496. <div id="setIndexTerm,RstGenerator,IndexEntryKind,string,string,string,string,string,int">
  497. <dt><pre><span class="Keyword">proc</span> <a href="#setIndexTerm%2CRstGenerator%2CIndexEntryKind%2Cstring%2Cstring%2Cstring%2Cstring%2Cstring%2Cint"><span class="Identifier">setIndexTerm</span></a><span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">k</span><span class="Other">:</span> <a href="rstidx.html#IndexEntryKind"><span class="Identifier">IndexEntryKind</span></a><span class="Other">;</span>
  498. <span class="Identifier">htmlFile</span><span class="Other">,</span> <span class="Identifier">id</span><span class="Other">,</span> <span class="Identifier">term</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">;</span> <span class="Identifier">linkTitle</span><span class="Other">,</span> <span class="Identifier">linkDesc</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">;</span> <span class="Identifier">line</span> <span class="Other">=</span> <span class="DecNumber">0</span><span class="Other">)</span> {.
  499. <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><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 class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  500. <dd>
  501. <p>Adds a <tt class="docutils literal"><span class="pre"><span class="Identifier">term</span></span></tt> to the index using the specified hyperlink identifier.</p>
  502. <p>A new entry will be added to the index using the format <tt class="docutils literal"><span class="pre">term&lt;tab&gt;file#id</span></tt>. The file part will come from the <tt class="docutils literal"><span class="pre"><span class="Identifier">htmlFile</span></span></tt> parameter.</p>
  503. <p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">id</span></span></tt> will be appended with a hash character only if its length is not zero, otherwise no specific anchor will be generated. In general you should only pass an empty <tt class="docutils literal"><span class="pre"><span class="Identifier">id</span></span></tt> value for the title of standalone rst documents (they are special for the <a class="reference external" href="#mergeIndexes,string">mergeIndexes()</a> proc, see <a class="reference external" href="docgen.html#index-idx-file-format">Index (idx) file format</a> for more information). Unlike other index terms, title entries are inserted at the beginning of the accumulated buffer to maintain a logical order of entries.</p>
  504. <p>If <tt class="docutils literal"><span class="pre"><span class="Identifier">linkTitle</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">linkDesc</span></span></tt> are not the empty string, two additional columns with their contents will be added.</p>
  505. <p>The index won't be written to disk unless you call <a class="reference external" href="#writeIndexFile,RstGenerator,string">writeIndexFile()</a>. The purpose of the index is documented in the <a class="reference external" href="docgen.html#related-options-index-switch">docgen tools guide</a>.</p>
  506. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L325" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  507. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L325" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  508. </dd>
  509. </div>
  510. </div>
  511. <div id="traverseForIndex-procs-all">
  512. <div id="traverseForIndex,PDoc,PRstNode">
  513. <dt><pre><span class="Keyword">proc</span> <a href="#traverseForIndex%2CPDoc%2CPRstNode"><span class="Identifier">traverseForIndex</span></a><span class="Other">(</span><span class="Identifier">d</span><span class="Other">:</span> <span class="Identifier">PDoc</span><span class="Other">;</span> <span class="Identifier">n</span><span class="Other">:</span> <a href="rstast.html#PRstNode"><span class="Identifier">PRstNode</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span>
  514. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  515. <dd>
  516. A version of <a class="reference internal nimdoc" title="proc renderRstToOut(d: var RstGenerator; n: PRstNode; result: var string)" href="#renderRstToOut,RstGenerator,PRstNode,string">renderRstToOut</a> that only fills entries for <tt class="docutils literal"><span class="pre">.idx</span></tt> files.
  517. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L1108" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  518. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L1108" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  519. </dd>
  520. </div>
  521. </div>
  522. <div id="writeIndexFile-procs-all">
  523. <div id="writeIndexFile,RstGenerator,string">
  524. <dt><pre><span class="Keyword">proc</span> <a href="#writeIndexFile%2CRstGenerator%2Cstring"><span class="Identifier">writeIndexFile</span></a><span class="Other">(</span><span class="Identifier">g</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="rstgen.html#RstGenerator"><span class="Identifier">RstGenerator</span></a><span class="Other">;</span> <span class="Identifier">outfile</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">IOError</span><span class="Other">]</span><span class="Other">,</span>
  525. <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">WriteIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
  526. <dd>
  527. <p>Writes the current index buffer to the specified output file.</p>
  528. <p>You previously need to add entries to the index with the <a class="reference external" href="#setIndexTerm,RstGenerator,string,string,string,string,string">setIndexTerm()</a> proc. If the index is empty the file won't be created.</p>
  529. <a href="https://github.com/nim-lang/Nim/tree/devel/lib/packages/docutils/rstgen.nim#L186" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
  530. <a href="https://github.com/nim-lang/Nim/edit/devel/lib/packages/docutils/rstgen.nim#L186" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
  531. </dd>
  532. </div>
  533. </div>
  534. </dl>
  535. </div>
  536. </div>
  537. </div>
  538. <div class="twelve-columns footer">
  539. <span class="nim-sprite"></span>
  540. <br>
  541. <small style="color: var(--hint);">Made with Nim. Generated: 2024-12-25 08:35:55 UTC</small>
  542. </div>
  543. </div>
  544. </div>
  545. <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
  546. </body>
  547. </html>