levovix
/
Nim
mirror of https://github.com/nim-lang/Nim


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nim DocGen Tools Guide</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<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=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">Nim DocGen Tools Guide</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="introduction_toc" href="#introduction">Introduction</a></li>
<ul class="simple"><li><a class="reference" id="introduction-quick-start_toc" href="#introduction-quick-start">Quick start</a></li>
<li><a class="reference" id="introduction-documentation-comments_toc" href="#introduction-documentation-comments">Documentation Comments</a></li>
<li><a class="reference" id="introduction-structuring-output-directories_toc" href="#introduction-structuring-output-directories">Structuring output directories</a></li>
<li><a class="reference" id="introduction-index-files_toc" href="#introduction-index-files">Index files</a></li>
</ul><li><a class="reference" id="document-types_toc" href="#document-types">Document Types</a></li>
<ul class="simple"><li><a class="reference" id="document-types-example-of-nim-file-input_toc" href="#document-types-example-of-nim-file-input">Example of Nim file input</a></li>
<li><a class="reference" id="document-types-html_toc" href="#document-types-html">HTML</a></li>
<li><a class="reference" id="document-types-latex_toc" href="#document-types-latex">LaTeX</a></li>
<li><a class="reference" id="document-types-json_toc" href="#document-types-json">JSON</a></li>
</ul><li><a class="reference" id="simple-documentation-links_toc" href="#simple-documentation-links">Simple documentation links</a></li>
<ul class="simple"><li><a class="reference" id="simple-documentation-links-nim-local-referencing_toc" href="#simple-documentation-links-nim-local-referencing">Nim local referencing</a></li>
<li><a class="reference" id="simple-documentation-links-nim-external-referencing_toc" href="#simple-documentation-links-nim-external-referencing">Nim external referencing</a></li>
</ul><li><a class="reference" id="related-options_toc" href="#related-options">Related Options</a></li>
<ul class="simple"><li><a class="reference" id="related-options-project-switch_toc" href="#related-options-project-switch">Project switch</a></li>
<li><a class="reference" id="related-options-index-switch_toc" href="#related-options-index-switch">Index switch</a></li>
<li><a class="reference" id="related-options-buildindex-command_toc" href="#related-options-buildindex-command">Buildindex command</a></li>
<li><a class="reference" id="related-options-see-source-switch_toc" href="#related-options-see-source-switch">See source switch</a></li>
</ul><li><a class="reference" id="other-input-formats_toc" href="#other-input-formats">Other Input Formats</a></li>
<li><a class="reference" id="html-anchor-generation_toc" href="#html-anchor-generation">HTML anchor generation</a></li>
<li><a class="reference" id="index-idx-file-format_toc" href="#index-idx-file-format">Index (idx) file format</a></li>
<li><a class="reference" id="additional-resources_toc" href="#additional-resources">Additional resources</a></li>

</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/docgen.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/docgen.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Erik O'Leary</td></tr>
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
</tbody></table>
<h1><a class="toc-backref" id="introduction" href="#introduction">Introduction</a></h1><p>This document describes the <span id="documentation-generation-tools_1">documentation generation tools</span> built into the <a class="reference external" href="nimc.html">Nim compiler</a>, which can generate HTML, Latex and JSON output from input <tt class="docutils literal"><span class="pre">.nim</span></tt> files and projects. The output documentation will include the module dependencies (<tt class="docutils literal"><span class="pre"><span class="Keyword">import</span></span></tt>), any top-level documentation comments (<tt class="docutils literal"><span class="pre"><span class="Comment">##</span></span></tt>), and exported symbols (<tt class="docutils literal"><span class="pre"><span class="Operator">*</span></span></tt>), including procedures, types, and variables.</p>
<table border="1" class="docutils"><tr><th>command</th><th>output format</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.html</span></tt> HTML</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc2tex</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.tex</span></tt> LaTeX</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">jsondoc</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.json</span></tt> JSON</td></tr>
</table><p>Nim can generate HTML and LaTeX from input Markdown and RST (reStructuredText) files as well, which is intended for writing standalone documents like user's guides and technical specifications. See <a class="reference external" href="./markdown_rst.html">Nim-flavored Markdown and reStructuredText</a> document for the description of this feature and particularly section <a class="reference external" href="./markdown_rst.html#command-line-usage">Nim-flavored Markdown and reStructuredText: Command line usage</a> for the full list of supported commands.</p>

<h2><a class="toc-backref" id="introduction-quick-start" href="#introduction-quick-start">Quick start</a></h2><p>Generate HTML documentation for a file:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="Identifier">&lt;filename&gt;.nim</span></pre></p>
<p>Generate HTML documentation for a whole project:</p>
<p><pre class="listing"><span class="Comment"># delete any htmldocs/*.idx file before starting</span>
<span class="program">nim</span> <span class="option">doc</span> <span class="option">--project</span> <span class="option">--index:on</span> <span class="Identifier">--git.url:&lt;url&gt;</span> <span class="Identifier">--git.commit:&lt;tag&gt;</span> <span class="option">--outdir:htmldocs</span> <span class="Identifier">&lt;main_filename&gt;.nim</span>
<span class="Comment"># this will generate html files, a theindex.html index, css and js under `htmldocs`</span>
<span class="Comment"># See also `--docroot` to specify a relative root.</span>
<span class="Comment"># to get search (dochacks.js) to work locally, you need a server otherwise</span>
<span class="Comment"># CORS will prevent opening file:// urls; this works:</span>
<span class="program">python3</span> <span class="option">-m</span> <span class="Identifier">http.server</span> <span class="option">7029</span> <span class="option">--directory</span> <span class="option">htmldocs</span>
<span class="Comment"># When --outdir is omitted it defaults to $projectPath/htmldocs,</span>
<span class="Comment"># or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;</span>
<span class="Comment"># and likewise without `--project`.</span>
<span class="Comment"># Adding `-r` will open in a browser directly.</span>
<span class="Comment"># Use `--showNonExports` to show non-exported fields of an exported type.</span></pre></p>

<h2><a class="toc-backref" id="introduction-documentation-comments" href="#introduction-documentation-comments">Documentation Comments</a></h2><p>Any comments which are preceded by a double-hash (<tt class="docutils literal"><span class="pre"><span class="Comment">##</span></span></tt>), are interpreted as documentation.  Comments are parsed as RST (see <a class="reference external" href=" https://docutils.sourceforge.net/docs/user/rst/quickref.html">reference</a>), providing Nim module authors the ability to easily generate richly formatted documentation with only their well-documented code! Basic Markdown syntax is also supported inside the doc comments.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Person</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Comment">## This type contains a description of a person</span>
  <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
  <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>Outputs:</p>
<pre>Person* = object
  name: string
  age: int</pre>
<p>This type contains a description of a person</p>
<p>Field documentation comments can be added to fields like so:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">numValues</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Comment">## \</span>
  <span class="Comment">## `numValues` stores the number of values</span></pre></p>
<p>Note that without the <tt class="docutils literal"><span class="pre"><span class="Operator">*</span></span></tt> following the name of the type, the documentation for this type would not be generated. Documentation will only be generated for <em>exported</em> types/procedures/etc.</p>
<p>It's recommended to always add exactly <strong>one</strong> space after <tt class="docutils literal"><span class="pre"><span class="Comment">##</span></span></tt> for readability of comments — this extra space will be cropped from the parsed comments and won't influence RST formatting.</p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
<p>Generally, this baseline indentation level inside a documentation comment may not be 1: it can be any since it is determined by the offset of the first non-whitespace character in the comment. After that indentation <strong>must</strong> be consistent on the following lines of the same comment. If you still need to add an additional indentation at the very beginning (for RST block quote syntax) use backslash \ before it:</p>
<p><pre class="listing"><span class="Comment">## \</span>
<span class="Comment">##</span>
<span class="Comment">##    Block quote at the first line.</span>
<span class="Comment">##</span>
<span class="Comment">## Paragraph.</span></pre></p>
</div>

<h2><a class="toc-backref" id="introduction-structuring-output-directories" href="#introduction-structuring-output-directories">Structuring output directories</a></h2><p>Basic directory for output is set by <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> switch, by default <tt class="docutils literal"><span class="pre"><span class="Identifier">OUTDIR</span></span></tt> is <tt class="docutils literal"><span class="pre">htmldocs</span></tt> sub-directory in the directory of the processed file.</p>
<p>There are 2 basic options as to how generated HTML output files are stored:</p>
<ol class="simple"><li>complex hierarchy when docgen-compiling with <tt class="docutils literal"><span class="pre option">--project</span></tt>, which follows directory structure of the project itself. So <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt> replicates project's directory structure inside <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> directory. <tt class="docutils literal"><span class="pre option">--project</span></tt> is well suited for projects that have 1 main module. File name clashes are impossible in this case.</li>
<li>flattened structure, where user-provided script goes through all needed input files and calls commands like <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt> with <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> switch, thus putting all HTML (and <tt class="docutils literal"><span class="pre">.idx</span></tt>) files into 1 directory.<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Important:</b></span>
Make sure that you don't have files with same base name like <tt class="docutils literal"><span class="pre">x.nim</span></tt> and <tt class="docutils literal"><span class="pre">x.md</span></tt> in the same package, otherwise you'll have name conflict for <tt class="docutils literal"><span class="pre">x.html</span></tt>.</div>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Tip:</b></span>
<p>To structure your output directories and avoid file name clashes you can split your project into different <em>packages</em> -- parts of your repository that are docgen-compiled with different <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> options.</p>
<p>An example of such strategy is Nim repository itself which has:</p>
<ul class="simple"><li>its stdlib <tt class="docutils literal"><span class="pre">.nim</span></tt> files from different directories and <tt class="docutils literal"><span class="pre">.md</span></tt> documentation from <tt class="docutils literal"><span class="pre">doc/</span></tt> directory are all docgen-compiled into <tt class="docutils literal"><span class="pre option">--outdir:web/upload/&lt;version&gt;/</span></tt> directory</li>
<li>its <tt class="docutils literal"><span class="pre">.nim</span></tt> files from <tt class="docutils literal"><span class="pre">compiler/</span></tt> directory are docgen-compiled into <tt class="docutils literal"><span class="pre option">--outdir:web/upload/&lt;version&gt;/compiler/</span></tt> directory. Interestingly, it's compiled with complex hierarchy using <tt class="docutils literal"><span class="pre option">--project</span></tt> switch.</li>
</ul>
<p>Contents of <tt class="docutils literal"><span class="pre">web/upload/&lt;version&gt;</span></tt> are then deployed into Nim's Web server.</p>
<p>This output directory structure allows to work correctly with files like <tt class="docutils literal"><span class="pre">compiler/docgen.nim</span></tt> (implementation) and <tt class="docutils literal"><span class="pre">doc/docgen.md</span></tt> (user documentation) in 1 repository.</p>
</div>
</li>
</ol>

<h2><a class="toc-backref" id="introduction-index-files" href="#introduction-index-files">Index files</a></h2><p>Index (<tt class="docutils literal"><span class="pre">.idx</span></tt>) files are used for 2 different purposes:</p>
<ol class="simple"><li>easy cross-referencing between different <tt class="docutils literal"><span class="pre">.nim</span></tt> and/or <tt class="docutils literal"><span class="pre">.md</span></tt> / <tt class="docutils literal"><span class="pre">.rst</span></tt> files described in <a class="reference internal" href="#simple-documentation-links-nim-external-referencing">Nim external referencing</a></li>
<li>creating a whole-project index for searching of symbols and keywords, see <a class="reference internal" href="#related-options-buildindex-command">Buildindex command</a>.</li>
</ol>

<h1><a class="toc-backref" id="document-types" href="#document-types">Document Types</a></h1>
<h2><a class="toc-backref" id="document-types-example-of-nim-file-input" href="#document-types-example-of-nim-file-input">Example of Nim file input</a></h2><p>The following examples will generate documentation for this sample <em>Nim</em> module, aptly named <tt class="docutils literal"><span class="pre">doc/docgen_sample.nim</span></tt>:</p>
<p><pre class="listing"><span class="Comment">## This module is a sample.</span>

<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>

<span class="Keyword">proc</span> <span class="Identifier">helloWorld</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">times</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment">## Takes an integer and outputs</span>
  <span class="Comment">## as many indented &quot;hello world!&quot;s</span>

  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="DecNumber">0</span> <span class="Operator">..</span> <span class="Identifier">times</span><span class="Operator">-</span><span class="DecNumber">1</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;hello world!&quot;</span><span class="Operator">.</span><span class="Identifier">indent</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># using indent to avoid `UnusedImport`</span>

<span class="Identifier">helloWorld</span><span class="Punctuation">(</span><span class="DecNumber">5</span><span class="Punctuation">)</span>
</pre></p>
<p>All the below commands save their output to <tt class="docutils literal"><span class="pre">htmldocs</span></tt> directory relative to the directory of file; hence the output for this sample will be in <tt class="docutils literal"><span class="pre">doc/htmldocs</span></tt>.</p>

<h2><a class="toc-backref" id="document-types-html" href="#document-types-html">HTML</a></h2><p>The generation of HTML documents is done via the <tt class="docutils literal"><span class="pre option">doc</span></tt> command. This command takes either a single <tt class="docutils literal"><span class="pre">.nim</span></tt> file, outputting a single <tt class="docutils literal"><span class="pre">.html</span></tt> file with the same base filename, or multiple <tt class="docutils literal"><span class="pre">.nim</span></tt> files, outputting multiple <tt class="docutils literal"><span class="pre">.html</span></tt> files and, optionally, an index file.</p>
<p>The <tt class="docutils literal"><span class="pre option">doc</span></tt> command:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="Identifier">docgen_sample.nim</span></pre></p>
<p>Partial Output:</p>
<pre>...
proc helloWorld(times: int) {.raises: [], tags: [].}
...</pre>
<p>The full output can be seen here: <a class="reference external" href="docgen_sample.html">docgen_sample.html</a>. It runs after semantic checking and includes pragmas attached implicitly by the compiler.</p>

<h2><a class="toc-backref" id="document-types-latex" href="#document-types-latex">LaTeX</a></h2><p>LaTeX files are intended to be converted to PDF, especially for offline reading or making hard copies. (LaTeX output is oftentimes better than HTML -&gt; PDF conversion).</p>
<p>The <tt class="docutils literal"><span class="pre option">doc2tex</span></tt> command:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">doc2tex</span> <span class="Identifier">docgen_sample.nim</span>
<span class="program">cd</span> <span class="option">htmldocs</span>
<span class="program">xelatex</span> <span class="Identifier">docgen_sample.tex</span>
<span class="program">xelatex</span> <span class="Identifier">docgen_sample.tex</span>
<span class="Comment"># It is usually necessary to run `xelatex` 2 times (or even 3 times for</span>
<span class="Comment"># large documents) to get all labels generated.</span>
<span class="Comment"># That depends on this warning in the end of `xelatex` output:</span>
<span class="Comment">#   LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.</span></pre></p>
<p>The output is <tt class="docutils literal"><span class="pre">docgen_sample.pdf</span></tt>.</p>

<h2><a class="toc-backref" id="document-types-json" href="#document-types-json">JSON</a></h2><p>The generation of JSON documents is done via the <tt class="docutils literal"><span class="pre option">jsondoc</span></tt> command. This command takes in a <tt class="docutils literal"><span class="pre">.nim</span></tt> file and outputs a <tt class="docutils literal"><span class="pre">.json</span></tt> file with the same base filename. Note that this tool is built off of the <tt class="docutils literal"><span class="pre option">doc</span></tt> command (previously <tt class="docutils literal"><span class="pre option">doc2</span></tt>), and contains the same information.</p>
<p>The <tt class="docutils literal"><span class="pre option">jsondoc</span></tt> command:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">jsondoc</span> <span class="Identifier">docgen_sample.nim</span></pre></p>
<p>Output:</p>
<pre>{
  &quot;orig&quot;: &quot;docgen_sample.nim&quot;,
  &quot;nimble&quot;: &quot;&quot;,
  &quot;moduleDescription&quot;: &quot;This module is a sample&quot;,
  &quot;entries&quot;: [
    {
      &quot;name&quot;: &quot;helloWorld&quot;,
      &quot;type&quot;: &quot;skProc&quot;,
      &quot;line&quot;: 5,
      &quot;col&quot;: 0,
      &quot;description&quot;: &quot;Takes an integer and outputs as many &amp;quot;hello world!&amp;quot;s&quot;,
      &quot;code&quot;: &quot;proc helloWorld(times: int) {.raises: [], tags: [].}&quot;
    }
  ]
}</pre>
<p>Similarly to the old <tt class="docutils literal"><span class="pre option">doc</span></tt> command, the old <tt class="docutils literal"><span class="pre option">jsondoc</span></tt> command has been renamed to <tt class="docutils literal"><span class="pre option">jsondoc0</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre option">jsondoc0</span></tt> command:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">jsondoc0</span> <span class="Identifier">docgen_sample.nim</span></pre></p>
<p>Output:</p>
<pre>[
  {
    &quot;comment&quot;: &quot;This module is a sample.&quot;
  },
  {
    &quot;name&quot;: &quot;helloWorld&quot;,
    &quot;type&quot;: &quot;skProc&quot;,
    &quot;description&quot;: &quot;Takes an integer and outputs as many &amp;quot;hello world!&amp;quot;s&quot;,
    &quot;code&quot;: &quot;proc helloWorld*(times: int)&quot;
  }
]</pre>
<p>Note that the <tt class="docutils literal"><span class="pre option">jsondoc</span></tt> command outputs its JSON without pretty-printing it, while <tt class="docutils literal"><span class="pre option">jsondoc0</span></tt> outputs pretty-printed JSON.</p>

<h1><a class="toc-backref" id="simple-documentation-links" href="#simple-documentation-links">Simple documentation links</a></h1><p>It's possible to use normal Markdown/RST syntax to <em>manually</em> reference Nim symbols using HTML anchors, however Nim has an <em>automatic</em> facility that makes referencing inside <tt class="docutils literal"><span class="pre">.nim</span></tt> and <tt class="docutils literal"><span class="pre">.md/.rst</span></tt> files and between them easy and seamless. The point is that such links will be resolved automatically by <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt> (or <tt class="docutils literal"><span class="pre option">md2html</span></tt>, or <tt class="docutils literal"><span class="pre option">jsondoc</span></tt>, or <tt class="docutils literal"><span class="pre option">doc2tex</span></tt>, ...). And, unlike manual links, such automatic links <strong>check</strong> that their target exists -- a warning is emitted for any broken link, so you avoid broken links in your project.</p>
<p>Nim treats both <tt class="docutils literal"><span class="pre">.md/.rst</span></tt> files and <tt class="docutils literal"><span class="pre">.nim</span></tt> modules (their doc comment part) as <em>documents</em> uniformly. Hence all directions of referencing are equally possible having the same syntax:</p>
<ol class="simple"><li><tt class="docutils literal"><span class="pre">.md/rst</span></tt> -&gt; itself (internal). See <a class="reference external" href="./markdown_rst.html#referencing-markup-local-referencing">Nim-flavored Markdown and reStructuredText: Markup local referencing</a>.</li>
<li><tt class="docutils literal"><span class="pre">.md/rst</span></tt> -&gt; external <tt class="docutils literal"><span class="pre">.md/rst</span></tt>. See <a class="reference external" href="./markdown_rst.html#referencing-markup-external-referencing">Nim-flavored Markdown and reStructuredText: Markup external referencing</a>. To summarize, referencing in <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">md</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">rst</span></span></tt> files was already described in <a class="reference external" href="./markdown_rst.html">Nim-flavored Markdown and reStructuredText</a> (particularly it described usage of index files for referencing), while in this document we focus on Nim-specific details.</li>
<li><tt class="docutils literal"><span class="pre">.md/rst</span></tt> -&gt; external <tt class="docutils literal"><span class="pre">.nim</span></tt>. See <a class="reference internal" href="#simple-documentation-links-nim-external-referencing">Nim external referencing</a>.</li>
<li><tt class="docutils literal"><span class="pre">.nim</span></tt> -&gt; itself (internal). See <a class="reference internal" href="#simple-documentation-links-nim-local-referencing">Nim local referencing</a>.</li>
<li><tt class="docutils literal"><span class="pre">.nim</span></tt> -&gt; external <tt class="docutils literal"><span class="pre">.md/rst</span></tt>. See <a class="reference external" href="./markdown_rst.html#referencing-markup-external-referencing">Nim-flavored Markdown and reStructuredText: Markup external referencing</a>.</li>
<li><tt class="docutils literal"><span class="pre">.nim</span></tt> -&gt; external <tt class="docutils literal"><span class="pre">.nim</span></tt>. See <a class="reference internal" href="#simple-documentation-links-nim-external-referencing">Nim external referencing</a>.</li>
</ol>
<p>To put it shortly, local referencing always works out of the box, external referencing requires to use <tt class="docutils literal"><span class="pre">.. importdoc:: &lt;file&gt;</span></tt> directive to import <tt class="docutils literal"><span class="pre"><span class="Identifier">file</span></span></tt> and to ensure that the corresponding <tt class="docutils literal"><span class="pre">.idx</span></tt> file was generated.</p>
<p>Syntax for referencing is basically the same as for normal markup. Recall from <a class="reference external" href="./markdown_rst.html#referencing">Nim-flavored Markdown and reStructuredText: Referencing</a> that our parser supports two equivalent syntaxes for referencing, Markdown and RST one. So to reference <tt class="docutils literal"><span class="pre">proc f</span></tt> one should use something like that, depending on markup type:</p>
<pre>Markdown                    RST

Ref. [proc f] or [f]        Ref. `proc f`_ or just f_ for a one-word case</pre>

<h2><a class="toc-backref" id="simple-documentation-links-nim-local-referencing" href="#simple-documentation-links-nim-local-referencing">Nim local referencing</a></h2><p>You can reference Nim identifiers from Nim documentation comments inside their <tt class="docutils literal"><span class="pre">.nim</span></tt> file (or inside a <tt class="docutils literal"><span class="pre">.rst</span></tt> file included from a <tt class="docutils literal"><span class="pre">.nim</span></tt>). This pertains to any exported symbol like <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt>, etc. Link text is either one word or a group of words enclosed by delimiters (brackets <tt class="docutils literal"><span class="pre">[...]</span></tt> for Markdown or backticks <tt class="docutils literal"><span class="pre"><span class="Punctuation">`</span><span class="Operator">...</span><span class="Punctuation">`</span><span class="Identifier">_</span></span></tt> for RST). Link text will be displayed <em>as is</em> while <em>link target</em> will be set to the anchor <sup><strong><a class="reference internal" href="#footnote-1">[1]</a></strong></sup> of Nim symbol that corresponds to link text.</p>
<p><sup><strong><a class="reference internal" href="#footnote-1">[1]</a></strong></sup> anchors' format is described in <a class="reference internal" href="#html-anchor-generation">HTML anchor generation</a> section below.</p>
<p>If you have a constant:</p>
<p><pre class="listing"><span class="Keyword">const</span> <span class="Identifier">pi</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="FloatNumber">3.14</span></pre></p>
<p>then it should be referenced in one of the 2 forms:</p>
<ol class="upperalpha simple"><li>non-qualified (no symbol kind specification):<pre>pi_</pre>
</li>
<li>qualified (with symbol kind specification):<pre>`const pi`_</pre>
</li>
</ol>
<p>For routine kinds there are more options. Consider this definition:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">float</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span></pre></p>
<p>Generally following syntax is allowed for referencing <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt>:</p>
<ul class="simple"><li>short (without parameters):<ol class="upperalpha simple"><li>non-qualified:<pre>foo_</pre>
</li>
<li>qualified:<pre>`proc foo`_</pre>
</li>
</ol>
</li>
<li>longer variants (with parameters):<ol class="upperalpha simple"><li>non-qualified:<ol class="simple"><li>specifying parameters names:<pre>`foo(a, b)`_</pre>
</li>
<li>specifying parameters types:<pre>`foo(int, float)`_</pre>
</li>
<li>specifying both names and types:<pre>`foo(a: int, b: float)`_</pre>
</li>
<li>output parameter can also be specified if you wish:<pre>`foo(a: int, b: float): string`_</pre>
</li>
</ol>
</li>
<li>qualified: all 4 options above are valid. Particularly you can use the full format:<pre>`proc foo(a: int, b: float): string`_</pre>
</li>
</ol>
</li>
</ul>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Tip:</b></span>
Avoid cluttering your text with extraneous information by using one of shorter forms:<pre>binarySearch_
`binarySearch(a, key, cmp)`_</pre>
<p>Brevity is better for reading! If you use a short form and have an ambiguity problem (see below) then just add some additional info.</p>
</div>
<p>Symbol kind like <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> can also be specified in the postfix form:</p>
<pre>`foo proc`_
`walkDir(d: string) iterator`_</pre>
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
An ambiguity in resolving documentation links may arise because of:<ol class="simple"><li>clash with other RST anchors<ul class="simple"><li>manually setup anchors</li>
<li>automatically set up, e.g. section names</li>
</ul>
</li>
<li>collision with other Nim symbols:<ul class="simple"><li>routines with different parameters can exist e.g. for <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">template</span></span></tt>. In this case they are split between their corresponding sections in output file. Qualified references are useful in this case -- just disambiguate by referring to these sections explicitly:<pre>See `foo proc`_ and `foo template`_.</pre>
</li>
<li>because in Nim <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt> belong to different namespaces, so there can be a collision even if parameters are the same. Use <tt class="docutils literal"><span class="pre">`proc foo`_</span></tt> or <tt class="docutils literal"><span class="pre">`iterator foo`_</span></tt> then.</li>
</ul>
</li>
</ol>
<p>Any ambiguity is always reported with Nim compiler warnings and an anchor with higher priority is selected. Manual anchors have highest priority, then go automatic RST anchors; then Nim-generated anchors (while procs have higher priority than other Nim symbol kinds).</p>
</div>
<p>Generic parameters can also be used. All in all, this long form will be recognized fine:</p>
<pre>`proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_</pre>
<p><strong>Limitations</strong>:</p>
<ol class="simple"><li><p>The parameters of a nested routine type can be specified only with types (without parameter names, see form A.2 above). E.g. for this signature:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">binarySearch</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">K</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">key</span><span class="Punctuation">:</span> <span class="Identifier">K</span><span class="Punctuation">;</span>
                         <span class="Identifier">cmp</span><span class="Punctuation">:</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">K</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
                                    <span class="Operator">~~</span>    <span class="Operator">~~</span>   <span class="Operator">~~~~~</span></pre></p>
<p>you cannot use names underlined by <tt class="docutils literal"><span class="pre"><span class="Operator">~~</span></span></tt> so it must be referenced with <tt class="docutils literal"><span class="pre">cmp: proc(T, K)</span></tt>. Hence these forms are valid:</p>
<pre>`binarySearch(a: openArray[T], key: K, cmp: proc(T, K))`_
`binarySearch(openArray[T], K, proc(T, K))`_
`binarySearch(a, key, cmp)`_</pre>
</li>
<li>Default values in routine parameters are not recognized, one needs to specify the type and/or name instead. E.g. for referencing <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">f</span><span class="Punctuation">(</span><span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">7</span><span class="Punctuation">)</span></span></tt> use one of the mentioned forms:<pre>`f(int)`_ or `f(x)`_ or `f(x: int)`_.</pre>
</li>
<li>Generic parameters must be given the same way as in the definition of referenced symbol.<ul class="simple"><li>their names should be the same</li>
<li>parameters list should be given the same way, e.g. without substitutions between commas (,) and semicolons (;).</li>
</ul>
</li>
</ol>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
<p>A bit special case is operators (as their signature is also defined with <tt class="docutils literal"><span class="pre"><span class="Punctuation">`</span></span></tt>):</p>
<p><pre class="listing"><span class="Keyword">func</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">MyType</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
<span class="Keyword">func</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">T</span></pre></p>
<p>A short form works without additional backticks:</p>
<pre>`$`_
`[]`_</pre>
<p>However for fully-qualified reference copy-pasting backticks (`) into other backticks will not work in our RST parser (because we use Markdown-like inline markup rules). You need either to delete backticks or keep them and escape with backslash \:</p>
<pre>no backticks: `func $`_
escaped:  `func \`$\``_
no backticks: `func [][T](x: openArray[T]): T`_
escaped:  `func \`[]\`[T](x: openArray[T]): T`_</pre>
</div>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
Types that defined as <tt class="docutils literal"><span class="pre"><span class="Keyword">enum</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Keyword">tuple</span></span></tt> can also be referenced with those names directly (instead of <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt>):<pre>type CopyFlag = enum
  ...
## Ref. `CopyFlag enum`_</pre>
</div>

<h2><a class="toc-backref" id="simple-documentation-links-nim-external-referencing" href="#simple-documentation-links-nim-external-referencing">Nim external referencing</a></h2><p>Just like for <a class="reference external" href="./markdown_rst.html#referencing-markup-external-referencing">Nim-flavored Markdown and reStructuredText: Markup external referencing</a>, which saves markup anchors, the Nim symbols are also saved in <tt class="docutils literal"><span class="pre">.idx</span></tt> files, so one needs to generate them beforehand, and they should be loaded by an <tt class="docutils literal"><span class="pre">.. importdoc::</span></tt> directive. Arguments to <tt class="docutils literal"><span class="pre">.. importdoc::</span></tt> is a comma-separated list of Nim modules or Markdown/RST documents.</p>
<p><tt class="docutils literal"><span class="pre option">--index:only</span></tt> tells Nim to only generate <tt class="docutils literal"><span class="pre">.idx</span></tt> file and do <strong>not</strong> attempt to generate HTML/LaTeX output. For <tt class="docutils literal"><span class="pre">.nim</span></tt> modules there are 2 alternatives to work with <tt class="docutils literal"><span class="pre">.idx</span></tt> files:</p>
<ol class="simple"><li><p>using <a class="reference internal" href="#related-options-project-switch">Project switch</a> implies generation of <tt class="docutils literal"><span class="pre">.idx</span></tt> files, however, if <tt class="docutils literal"><span class="pre">importdoc</span></tt> is called on upper modules as its arguments, their <tt class="docutils literal"><span class="pre">.idx</span></tt> are not yet created. Thus one should generate <strong>all</strong> required <tt class="docutils literal"><span class="pre">.idx</span></tt> first:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="option">--project</span> <span class="option">--index:only</span> <span class="Identifier">&lt;main&gt;.nim</span>
<span class="program">nim</span> <span class="option">doc</span> <span class="option">--project</span> <span class="Identifier">&lt;main&gt;.nim</span></pre></p>
</li>
<li>or run <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span> <span class="option">--index:only</span> <span class="Identifier">&lt;module.nim&gt;</span></span></tt> command for <strong>all</strong> (used) Nim modules in your project. Then run <tt class="docutils literal"><span class="pre"><span class="Identifier">nim</span> <span class="Identifier">doc</span> <span class="Operator">&lt;</span><span class="Identifier">module</span><span class="Operator">.</span><span class="Identifier">nim</span><span class="Operator">&gt;</span></span></tt> on them for output HTML generation.<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
A mere <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span> <span class="option">--index:on</span></span></tt> may fail on an attempt to do <tt class="docutils literal"><span class="pre">importdoc</span></tt> from another module (for which <tt class="docutils literal"><span class="pre">.idx</span></tt> was not yet generated), that's why <tt class="docutils literal"><span class="pre option">--index:only</span></tt> shall be used instead.</div>
<p>For <tt class="docutils literal"><span class="pre">.md</span></tt>/<tt class="docutils literal"><span class="pre">.rst</span></tt> markup documents point 2 is the only option.</p>
</li>
</ol>
<p>Then, you can freely use something like this in <tt class="docutils literal"><span class="pre">your_module.nim</span></tt>:</p>
<p><pre class="listing"><span class="Comment">## .. importdoc::  user_manual.md, another_module.nim</span>

<span class="Operator">...</span>
<span class="Comment">## Ref. [some section from User Manual].</span>

<span class="Operator">...</span>
<span class="Comment">## Ref. [proc f]</span>
<span class="Comment">## (assuming you have a proc `f` in ``another_module``).</span></pre></p>
<p>and compile it by <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">doc</span></span></tt>. Note that link text will be automatically prefixed by the module name of symbol, so you will see something like &quot;Ref. <a class="reference external" href="#">another_module: proc f</a>&quot; in the generated output.</p>
<p>It's also possible to reference a whole module by prefixing or suffixing full canonical module name with &quot;module&quot;:</p>
<pre>Ref. [module subdir/name] or [subdir/name module].</pre>
<p>Markup documents as a whole can be referenced just by their title (or by their file name if the title was not set) without any prefix.</p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Tip:</b></span>
During development process the stage of <tt class="docutils literal"><span class="pre">.idx</span></tt> files generation can be done only <em>once</em>, after that you use already generated <tt class="docutils literal"><span class="pre">.idx</span></tt> files while working with a document <em>being developed</em> (unless you do incompatible changes to <em>referenced</em> documents).</div>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Hint:</b></span>
After changing a <em>referenced</em> document file one may need to regenerate its corresponding <tt class="docutils literal"><span class="pre">.idx</span></tt> file to get correct results. Of course, when referencing <em>internally</em> inside any given <tt class="docutils literal"><span class="pre">.nim</span></tt> file, it's not needed, one can even immediately use any freshly added anchor (a document's own <tt class="docutils literal"><span class="pre">.idx</span></tt> file is not used for resolving its internal links).</div>
<p>If an <tt class="docutils literal"><span class="pre">importdoc</span></tt> directive fails to find a <tt class="docutils literal"><span class="pre">.idx</span></tt>, then an error is emitted.</p>
<p>In case of such compilation failures please note that:</p>
<ul class="simple"><li><strong>all</strong> relative paths, given to <tt class="docutils literal"><span class="pre">importdoc</span></tt>, relate to insides of <tt class="docutils literal"><span class="pre">OUTDIR</span></tt>, and <strong>not</strong> project's directory structure.</li>
<li><tt class="docutils literal"><span class="pre">importdoc</span></tt> searches for <tt class="docutils literal"><span class="pre">.idx</span></tt> in <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> directory (<tt class="docutils literal"><span class="pre">htmldocs</span></tt> by default) and <strong>not</strong> around original modules, so:<div class="admonition admonition-info"><span class="admonition-info-text"><b>Tip:</b></span>
look into <tt class="docutils literal"><span class="pre">OUTDIR</span></tt> to understand what's going on.</div>
</li>
<li>also keep in mind that <tt class="docutils literal"><span class="pre">.html</span></tt> and <tt class="docutils literal"><span class="pre">.idx</span></tt> files should always be output to the same directory, so check this and, if it's not true, check that both runs <em>with</em> and <em>without</em> <tt class="docutils literal"><span class="pre option">--index:only</span></tt> have all other options the same.</li>
</ul>
<p>To summarize, for 2 basic options of <a class="reference internal" href="#introduction-structuring-output-directories">Structuring output directories</a> compilation options are different:</p>
<ol class="simple"><li><p>complex hierarchy with <tt class="docutils literal"><span class="pre option">--project</span></tt> switch.</p>
<p>As the <strong>original</strong> project's directory structure is replicated in <tt class="docutils literal"><span class="pre"><span class="Identifier">OUTDIR</span></span></tt>, all passed paths are related to this structure also.</p>
<p>E.g. if a module <tt class="docutils literal"><span class="pre">path1/module.nim</span></tt> does <tt class="docutils literal"><span class="pre">.. importdoc:: path2/another.nim</span></tt> then docgen tries to load file <tt class="docutils literal"><span class="pre">OUTDIR/path1/path2/another.idx</span></tt>.</p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
<p>markup documents are just placed into the specified directory <tt class="docutils literal"><span class="pre option">OUTDIR</span></tt> by default (i.e. they are <strong>not</strong> affected by <tt class="docutils literal"><span class="pre option">--project</span></tt>), so if you have <tt class="docutils literal"><span class="pre">PROJECT/doc/manual.md</span></tt> document and want to use complex hierarchy (with <tt class="docutils literal"><span class="pre">doc/</span></tt>), compile it with <tt class="docutils literal"><span class="pre option">--docroot</span></tt>:</p>
<p><pre class="listing"><span class="Comment"># 1st stage</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="option">--outdir:OUTDIR</span> <span class="Identifier">--docroot:/absolute/path/to/PROJECT</span> <span class="Identifier">\</span>
     <span class="program">--index:only</span> <span class="Identifier">PROJECT/doc/manual.md</span>
<span class="program">...</span>
<span class="Comment"># 2nd stage</span>
<span class="program">nim</span> <span class="option">md2html</span> <span class="option">--outdir:OUTDIR</span> <span class="Identifier">--docroot:/absolute/path/to/PROJECT</span> <span class="Identifier">\</span>
                  <span class="program">PROJECT/doc/manual.md</span></pre></p>
<p>Then the output file will be placed as <tt class="docutils literal"><span class="pre">OUTDIR/doc/manual.idx</span></tt>. So if you have <tt class="docutils literal"><span class="pre">PROJECT/path1/module.nim</span></tt>, then <tt class="docutils literal"><span class="pre">manual.md</span></tt> can be referenced as <tt class="docutils literal"><span class="pre">../doc/manual.md</span></tt>.</p>
</div>
</li>
<li><p>flattened structure.</p>
<p>E.g. if a module <tt class="docutils literal"><span class="pre">path1/module.nim</span></tt> does <tt class="docutils literal"><span class="pre">.. importdoc:: path2/another.nim</span></tt> then docgen tries to load <tt class="docutils literal"><span class="pre">OUTDIR/path2/another.idx</span></tt>, so the path <tt class="docutils literal"><span class="pre">path1</span></tt> does not matter and providing <tt class="docutils literal"><span class="pre">path2</span></tt> can be useful only in the case it contains another package that was placed there using <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR/path2</span></tt>.</p>
<p>The links' text will be prefixed as <tt class="docutils literal"><span class="pre">another: ...</span></tt> in both cases.</p>
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
Again, the same <tt class="docutils literal"><span class="pre option">--outdir:OUTDIR</span></tt> option should be provided to both <tt class="docutils literal"><span class="pre option">doc --index:only</span></tt> / <tt class="docutils literal"><span class="pre option">md2html --index:only</span></tt> and final generation by <tt class="docutils literal"><span class="pre option">doc</span></tt>/<tt class="docutils literal"><span class="pre option">md2html</span></tt> inside 1 package.</div>
</li>
</ol>
<p>To temporarily disable <tt class="docutils literal"><span class="pre">importdoc</span></tt>, e.g. if you don't need correct link resolution at the moment, use a <tt class="docutils literal"><span class="pre option">--noImportdoc</span></tt> switch (only warnings about unresolved links will be generated for external references).</p>

<h1><a class="toc-backref" id="related-options" href="#related-options">Related Options</a></h1>
<h2><a class="toc-backref" id="related-options-project-switch" href="#related-options-project-switch">Project switch</a></h2><p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="option">--project</span> <span class="Identifier">filename.nim</span></pre></p>
<p>This will recursively generate documentation of all Nim modules imported into the input module that belong to the Nimble package that <tt class="docutils literal"><span class="pre">filename.nim</span></tt> belongs to. The index files and the corresponding <tt class="docutils literal"><span class="pre">theindex.html</span></tt> will also be generated.</p>

<h2><a class="toc-backref" id="related-options-index-switch" href="#related-options-index-switch">Index switch</a></h2><p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="option">--index:on</span> <span class="Identifier">filename.nim</span></pre></p>
<p>This will generate an index of all the exported symbols in the input Nim module, and put it into a neighboring file with the extension of <tt class="docutils literal"><span class="pre">.idx</span></tt>. The index file is line-oriented (newlines have to be escaped). Each line represents a tab-separated record of several columns, the first two mandatory, the rest optional. See the <a class="reference internal" href="#index-idx-file-format">Index (idx) file format</a> section for details.</p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
<tt class="docutils literal"><span class="pre option">--index</span></tt> switch only affects creation of <tt class="docutils literal"><span class="pre">.idx</span></tt> index files, while user-searchable Index HTML file is created by <tt class="docutils literal"><span class="pre option">buildIndex</span></tt> command.</div>

<h2><a class="toc-backref" id="related-options-buildindex-command" href="#related-options-buildindex-command">Buildindex command</a></h2><p>Once index files have been generated for one or more modules, the Nim compiler command <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">buildIndex</span> <span class="option">directory</span></span></tt> can be run to go over all the index files in the specified directory to generate a <a class="reference external" href="theindex.html">theindex.html</a> file:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">buildIndex</span> <span class="Identifier">-o:path/to/htmldocs/theindex.html</span> <span class="Identifier">path/to/htmldocs</span></pre></p>

<h2><a class="toc-backref" id="related-options-see-source-switch" href="#related-options-see-source-switch">See source switch</a></h2><p><pre class="listing"><span class="program">nim</span> <span class="option">doc</span> <span class="Identifier">--git.url:&lt;url&gt;</span> <span class="Identifier">filename.nim</span></pre></p>
<p>With the <tt class="docutils literal"><span class="pre option">git.url</span></tt> switch the <em>See source</em> hyperlink will appear below each documented item in your source code pointing to the implementation of that item on a GitHub repository. You can click the link to see the implementation of the item.</p>
<p>The <tt class="docutils literal"><span class="pre option">git.commit</span></tt> switch overrides the hardcoded <tt class="docutils literal"><span class="pre"><span class="Identifier">devel</span></span></tt> branch in <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt>. This is useful to link to a different branch e.g. <tt class="docutils literal"><span class="pre option">--git.commit:master</span></tt>, or to a tag e.g. <tt class="docutils literal"><span class="pre option">--git.commit:1.2.3</span></tt> or a commit.</p>
<p>Source URLs are generated as <tt class="docutils literal"><span class="pre">href=&quot;${url}/tree/${commit}/${path}#L${line}&quot;</span></tt> by default and thus compatible with GitHub but not with GitLab.</p>
<p>Similarly, <tt class="docutils literal"><span class="pre option">git.devel</span></tt> switch overrides the hardcoded <tt class="docutils literal"><span class="pre"><span class="Identifier">devel</span></span></tt> branch for the <tt class="docutils literal"><span class="pre"><span class="Identifier">Edit</span></span></tt> link which is also useful if you have a different working branch than <tt class="docutils literal"><span class="pre"><span class="Identifier">devel</span></span></tt> e.g. <tt class="docutils literal"><span class="pre option">--git.devel:master</span></tt>.</p>
<p>Edit URLs are generated as <tt class="docutils literal"><span class="pre">href=&quot;${url}/tree/${devel}/${path}#L${line}&quot;</span></tt> by default.</p>
<p>You can edit <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt> and modify the <tt class="docutils literal"><span class="pre">doc.item.seesrc</span></tt> value with a hyperlink to your own code repository.</p>
<p>In the case of Nim's own documentation, the <tt class="docutils literal"><span class="pre"><span class="Identifier">commit</span></span></tt> value is just a commit hash to append to a formatted URL to <a class="reference external" href="https://github.com/nim-lang/Nim">https://github.com/nim-lang/Nim</a>.</p>

<h1><a class="toc-backref" id="other-input-formats" href="#other-input-formats">Other Input Formats</a></h1><p>The <em>Nim compiler</em> also has support for RST (reStructuredText) files with the <tt class="docutils literal"><span class="pre option">rst2html</span></tt> and <tt class="docutils literal"><span class="pre option">rst2tex</span></tt> commands. Documents like this one are initially written in a dialect of RST which adds support for Nim source code highlighting with the <tt class="docutils literal"><span class="pre">.. code-block:: nim</span></tt> prefix. <tt class="docutils literal"><span class="pre">code-block</span></tt> also supports highlighting of a few other languages supported by the <a class="reference external" href="highlite.html">packages/docutils/highlite module</a>.</p>
<p>See <a class="reference external" href="markdown_rst.html">Markdown and RST markup languages</a> for usage of those commands.</p>

<h1><a class="toc-backref" id="html-anchor-generation" href="#html-anchor-generation">HTML anchor generation</a></h1><p>When you run the <tt class="docutils literal"><span class="pre option">rst2html</span></tt> command, all sections in the RST document will get an anchor you can hyperlink to. Usually, you can guess the anchor lower casing the section title and replacing spaces with dashes, and in any case, you can get it from the table of contents. But when you run the <tt class="docutils literal"><span class="pre option">doc</span></tt> command to generate API documentation, some symbol get one or two anchors at the same time: a numerical identifier, or a plain name plus a complex name.</p>
<p>The numerical identifier is just a random number. The number gets assigned according to the section and position of the symbol in the file being processed and you should not rely on it being constant: if you add or remove a symbol the numbers may shuffle around.</p>
<p>The plain name of a symbol is a simplified version of its fully exported signature. Variables or constants have the same plain name symbol as their complex name. The plain name for procs, templates, and other callable types will be their unquoted value after removing parameters, return types, and pragmas. The plain name allows short and nice linking of symbols that works unless you have a module with collisions due to overloading.</p>
<p>If you hyperlink a plain name symbol and there are other matches on the same HTML file, most browsers will go to the first one. To differentiate the rest, you will need to use the complex name. A complex name for a callable type is made up of several parts:</p>
<p>(<strong>plain symbol</strong>)(<strong>.type</strong>),(<strong>first param</strong>)?(<strong>,param type</strong>)*</p>
<p>The first thing to note is that all callable types have at least a comma, even if they don't have any parameters. If there are parameters, they are represented by their types and will be comma-separated. To the plain symbol a suffix may be added depending on the type of the callable:</p>
<table border="1" class="docutils"><tr><th>Callable type</th><th>Suffix</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">func</span></span></tt></td><td><em>empty string</em></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">macro</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.m</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">method</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.e</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.i</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">template</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.t</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">converter</span></span></tt></td><td><tt class="docutils literal"><span class="pre">.c</span></tt></td></tr>
</table><p>The relationship of type to suffix is made by the proc <tt class="docutils literal"><span class="pre"><span class="Identifier">complexName</span></span></tt> in the <tt class="docutils literal"><span class="pre">compiler/docgen.nim</span></tt> file. Here are some examples of complex names for symbols in the <a class="reference external" href="system.html">system module</a>.</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Keyword">type</span> <span class="Identifier">SomeSignedInt</span> <span class="Operator">=</span> <span class="Identifier">int</span> <span class="Operator">|</span> <span class="Identifier">int8</span> <span class="Operator">|</span> <span class="Identifier">int16</span> <span class="Operator">|</span> <span class="Identifier">int32</span> <span class="Operator">|</span> <span class="Identifier">int64</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#SomeSignedInt">#SomeSignedInt</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">globalRaiseHook</span><span class="Punctuation">:</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">E_Base</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nimcall</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#globalRaiseHook">#globalRaiseHook</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">const</span> <span class="Identifier">NimVersion</span> <span class="Operator">=</span> <span class="StringLit">&quot;0.0.0&quot;</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#NimVersion">#NimVersion</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">getTotalMem</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">rtl</span><span class="Punctuation">,</span> <span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">tags</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#getTotalMem">#getTotalMem</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">len</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">magic</span><span class="Punctuation">:</span> <span class="StringLit">&quot;LengthSeq&quot;</span><span class="Punctuation">,</span> <span class="Identifier">noSideEffect</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#len,seq[T]">#len,seq[T]</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span> <span class="Identifier">pairs</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">key</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href="iterators.html#pairs.i,seq[T]">#pairs.i,seq[T]</a></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">template</span> <span class="Identifier">newException</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">exceptn</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">;</span> <span class="Identifier">message</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">parentException</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">Exception</span> <span class="Operator">=</span> <span class="Keyword">nil</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span></span></tt> <strong>=&gt;</strong> <a class="reference external" href=" system.html#newException.t,typedesc,string,ref.Exception">#newException.t,typedesc,string,ref.Exception</a></li>
</ul>

<h1><a class="toc-backref" id="index-idx-file-format" href="#index-idx-file-format">Index (idx) file format</a></h1><p>Files with the <tt class="docutils literal"><span class="pre">.idx</span></tt> extension are generated when you use the <a class="reference internal" href="#related-options-index-switch">Index switch</a> along with commands to generate documentation from source or text files. You can programmatically generate indices with the <a class="reference external" href=" rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string">setIndexTerm()</a> and <a class="reference external" href="rstgen.html#writeIndexFile,RstGenerator,string">writeIndexFile()</a> procs. The purpose of <tt class="docutils literal"><span class="pre"><span class="Identifier">idx</span></span></tt> files is to hold the interesting symbols and their HTML references so they can be later concatenated into a big index file with <a class="reference external" href="rstgen.html#mergeIndexes,string">mergeIndexes()</a>.  This section documents the file format in detail.</p>
<p>Index files are line-oriented and tab-separated (newline and tab characters have to be escaped). Each line represents a record with 6 fields. The content of these columns is:</p>
<ol class="simple" start="0"><li>Discriminator tag denoting type of the index entry, allowed values are:<dl class="docutils"><dt><tt class="docutils literal"><span class="pre"><span class="Identifier">markupTitle</span></span></tt></dt>
<dd>a title for <tt class="docutils literal"><span class="pre">.md</span></tt>/<tt class="docutils literal"><span class="pre">.rst</span></tt> document</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">nimTitle</span></span></tt></dt>
<dd>a title of <tt class="docutils literal"><span class="pre">.nim</span></tt> module</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">heading</span></span></tt></dt>
<dd>heading of sections, can be both in Nim and markup files</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">idx</span></span></tt></dt>
<dd>terms marked with :idx: role</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">nim</span></span></tt></dt>
<dd>a Nim symbol</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">nimgrp</span></span></tt></dt>
<dd>a Nim group for overloadable symbols like <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>s</dd>
</dl>
</li>
<li>Mandatory term being indexed. Terms can include quoting according to Nim's rules (e.g. `^`).</li>
<li>Base filename plus anchor hyperlink (e.g. <tt class="docutils literal"><span class="pre">algorithm.html#*,int,SortOrder</span></tt>).</li>
<li>Optional human-readable string to display as a hyperlink. If the value is not present or is the empty string, the hyperlink will be rendered using the term. Prefix whitespace indicates that this entry is not for an API symbol but for a TOC entry.</li>
<li>Optional title or description of the hyperlink. Browsers usually display this as a tooltip after hovering a moment over the hyperlink.</li>
<li>A line number of file where the entry was defined.</li>
</ol>
<p>The index generation tools differentiate between documentation generated from <tt class="docutils literal"><span class="pre">.nim</span></tt> files and documentation generated from <tt class="docutils literal"><span class="pre">.md</span></tt> or <tt class="docutils literal"><span class="pre">.rst</span></tt> files by tag <tt class="docutils literal"><span class="pre"><span class="Identifier">nimTitle</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">markupTitle</span></span></tt> in the 1st line of the <tt class="docutils literal"><span class="pre">.idx</span></tt> file.</p>

<h1><a class="toc-backref" id="additional-resources" href="#additional-resources">Additional resources</a></h1><ul class="simple"><li><a class="reference external" href="nimc.html#compiler-usage-commandminusline-switches">Nim Compiler User Guide</a></li>
<li>already mentioned documentation for <a class="reference external" href="markdown_rst.html">Markdown and RST markup languages</a>, which also contains the list of implemented features of these markup languages.</li>
<li>the implementation is in <a class="reference internal" href="#module compiler/docgen">module compiler/docgen</a>.</li>
</ul>
<p>The output for HTML and LaTeX comes from the <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt> and <tt class="docutils literal"><span class="pre">config/nimdoc.tex.cfg</span></tt> configuration files. You can add and modify these files to your project to change the look of the docgen output.</p>
<p>You can import the <a class="reference external" href="rstgen.html">packages/docutils/rstgen module</a> in your programs if you want to reuse the compiler's documentation generation procs. </p>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-02-06 22:27:32 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>