/usr/share/doc/nim-doc/html/docgen.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<!-- 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=="/>

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

<!-- CSS -->
<title>Nim DocGen Tools Guide</title>
<style type="text/css" >
/*
Stylesheet for use with Docutils/rst2html.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.

Modified from Chad Skeeters' rst2html-style
https://bitbucket.org/cskeeters/rst2html-style/

Modified by Boyd Greenfield
*/
/* SCSS variables */
/* Text weights */
/* Body colors */
/* Text colors */
/* Link colors */
/* Syntax highlighting colors */
/* Pct changes */
/* Mixins */
/* Body/layout */
html {
  font-size: 100%;
  -webkit-text-size-adjust: 100%;
  -ms-text-size-adjust: 100%; }

/* Where we want fancier font if available */
h1, h2, h3, h4, h5, h6, p.module-desc, table.docinfo + blockquote p, table.docinfo blockquote p, h1 + blockquote p {
  font-family: "Raleway", "Helvetica Neue", "HelveticaNeue", Helvetica, Arial, sans-serif !important; }

h1.title {
  font-weight: 900; }

body {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-weight: 400;
  font-size: 14px;
  line-height: 20px;
  color: #666;
  background-color: rgba(252, 248, 244, 0.75); }

/* Skeleton grid */
.container {
  position: relative;
  width: 100%;
  max-width: 960px;
  margin: 0 auto;
  padding: 0 20px;
  box-sizing: border-box; }

.column,
.columns {
  width: 100%;
  float: left;
  box-sizing: border-box; }

/* For devices larger than 400px */
@media (min-width: 400px) {
  .container {
    width: 100%;
    padding: 0; } }
/* For devices larger than 650px */
@media (min-width: 650px) {
  .container {
    width: 100%; }

  .column,
  .columns {
    margin-left: 4%; }

  .column:first-child,
  .columns:first-child {
    margin-left: 0; }

  .one.column,
  .one.columns {
    width: 4.66666666667%; }

  .two.columns {
    width: 13.3333333333%; }

  .three.columns {
    width: 22%; }

  .four.columns {
    width: 30.6666666667%; }

  .five.columns {
    width: 39.3333333333%; }

  .six.columns {
    width: 48%; }

  .seven.columns {
    width: 56.6666666667%; }

  .eight.columns {
    width: 65.3333333333%; }

  .nine.columns {
    width: 74.0%; }

  .ten.columns {
    width: 82.6666666667%; }

  .eleven.columns {
    width: 91.3333333333%; }

  .twelve.columns {
    width: 100%;
    margin-left: 0; }

  .one-third.column {
    width: 30.6666666667%; }

  .two-thirds.column {
    width: 65.3333333333%; } }
/* Customer Overrides */
.footer {
  text-align: center;
  color: #969696;
  padding-top: 10%; }

p.module-desc {
  font-size: 1.1em;
  color: #666666; }

a.link-seesrc {
  color: #aec7d2;
  font-style: italic; }

a.link-seesrc:hover {
  color: #6c9aae; }

#toc-list {
  word-wrap: break-word; }

ul.simple-toc {
  list-style: none; }

ul.simple-toc a.reference-toplevel {
  font-weight: bold;
  color: #0077b3; }

ul.simple-toc-section {
  list-style-type: circle;
  color: #6c9aae; }

ul.simple-toc-section a.reference {
  color: #0077b3; }

cite {
  font-style: italic !important; }

dt > pre {
  border-color: rgba(0, 0, 0, 0.15);
  background-color: transparent;
  margin: 15px 0px 5px; }

dd > pre {
  border-color: rgba(0, 0, 0, 0.1);
  background-color: whitesmoke;
  margin-top: 8px; }

.item > dd {
  margin-left: 10px;
  margin-bottom: 30px; }

/* Nim line-numbered tables */
.line-nums-table {
  width: 100%;
  table-layout: fixed; }

table.line-nums-table {
  border-radius: 4px;
  border: 1px solid #cccccc;
  background-color: whitesmoke;
  border-collapse: separate;
  margin-top: 15px;
  margin-bottom: 25px; }

.line-nums-table tbody {
  border: none; }

.line-nums-table td pre {
  border: none;
  background-color: transparent; }

.line-nums-table td.blob-line-nums {
  width: 28px; }

.line-nums-table td.blob-line-nums pre {
  color: #b0b0b0;
  -webkit-filter: opacity(75%);
  text-align: right;
  border-color: transparent;
  background-color: transparent;
  padding-left: 0px;
  margin-left: 0px;
  padding-right: 0px;
  margin-right: 0px; }

/* Docgen styles */
/* Links */
a {
  color: #0077b3;
  text-decoration: none; }

a:hover,
a:focus {
  color: #00334d;
  text-decoration: underline; }

a:visited {
  color: #00334d; }

a:focus {
  outline: thin dotted #2d2d2d;
  outline: 5px auto -webkit-focus-ring-color;
  outline-offset: -2px; }

a:hover,
a:active {
  outline: 0; }

sub,
sup {
  position: relative;
  font-size: 75%;
  line-height: 0;
  vertical-align: baseline; }

sup {
  top: -0.5em; }

sub {
  bottom: -0.25em; }

img {
  width: auto;
  height: auto;
  max-width: 100%;
  vertical-align: middle;
  border: 0;
  -ms-interpolation-mode: bicubic; }

@media print {
  * {
    color: black !important;
    text-shadow: none !important;
    background: transparent !important;
    box-shadow: none !important; }

  a,
  a:visited {
    text-decoration: underline; }

  a[href]:after {
    content: " (" attr(href) ")"; }

  abbr[title]:after {
    content: " (" attr(title) ")"; }

  .ir a:after,
  a[href^="javascript:"]:after,
  a[href^="#"]:after {
    content: ""; }

  pre,
  blockquote {
    border: 1px solid #999;
    page-break-inside: avoid; }

  thead {
    display: table-header-group; }

  tr,
  img {
    page-break-inside: avoid; }

  img {
    max-width: 100% !important; }

  @page {
    margin: 0.5cm; }

  h1 {
    page-break-before: always; }

  h1.title {
    page-break-before: avoid; }

  p,
  h2,
  h3 {
    orphans: 3;
    widows: 3; }

  h2,
  h3 {
    page-break-after: avoid; } }
.img-rounded {
  -webkit-border-radius: 6px;
  -moz-border-radius: 6px;
  border-radius: 6px; }

.img-polaroid {
  padding: 4px;
  background-color: rgba(252, 248, 244, 0.75);
  border: 1px solid #ccc;
  border: 1px solid rgba(0, 0, 0, 0.2);
  -webkit-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  -moz-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1); }

p {
  margin: 0 0 12px; }

small {
  font-size: 85%; }

strong {
  font-weight: 600; }

em {
  font-style: italic; }

cite {
  font-style: normal; }

h1,
h2,
h3,
h4,
h5,
h6 {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-weight: 600;
  line-height: 20px;
  color: inherit;
  text-rendering: optimizelegibility; }

h1 {
  font-size: 2em;
  padding-bottom: .15em;
  border-bottom: 1px solid #aaaaaa;
  margin-top: 1.0em;
  line-height: 1.2em; }

h1.title {
  padding-bottom: 1em;
  border-bottom: 0px;
  font-size: 2.75em; }

h2 {
  font-size: 1.5em;
  margin-top: 1.5em; }

h3 {
  font-size: 1.3em;
  font-style: italic;
  margin-top: 0.75em; }

h4 {
  font-size: 1.3em;
  margin-top: 0.5em; }

h5 {
  font-size: 1.2em;
  margin-top: 0.25em; }

h6 {
  font-size: 1.1em; }

ul,
ol {
  padding: 0;
  margin: 0 0 0px 15px; }

ul ul,
ul ol,
ol ol,
ol ul {
  margin-bottom: 0; }

li {
  line-height: 20px; }

dl {
  margin-bottom: 20px; }

dt,
dd {
  line-height: 20px; }

dt {
  font-weight: bold; }

dd {
  margin-left: 10px;
  margin-bottom: 26px; }

hr {
  margin: 20px 0;
  border: 0;
  border-top: 1px solid #eeeeee;
  border-bottom: 1px solid #ffffff; }

abbr[title],
abbr[data-original-title] {
  cursor: help;
  border-bottom: 1px dotted #999999; }

abbr.initialism {
  font-size: 90%;
  text-transform: uppercase; }

blockquote {
  padding: 0 0 0 15px;
  margin: 0 0 20px;
  border-left: 5px solid #EFEBE0; }

table.docinfo + blockquote, table.docinfo blockquote, h1 + blockquote {
  border-left: 5px solid #c9c9c9;
}

table.docinfo + blockquote p, table.docinfo blockquote p, h1 + blockquote p {
  margin-bottom: 0;
  font-size: 15px;
  font-weight: 200;
  line-height: 1.5;
  font-style: italic; }

q:before,
q:after,
blockquote:before,
blockquote:after {
  content: ""; }

address {
  display: block;
  margin-bottom: 20px;
  font-style: normal;
  line-height: 20px; }

code,
pre {
  font-family: "Source Code Pro", Monaco, Menlo, Consolas, "Courier New", monospace;
  padding: 0 3px 2px;
  font-weight: 500;
  font-size: 12px;
  color: #444444;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px; }

.pre {
  font-family: "Source Code Pro", Monaco, Menlo, Consolas, "Courier New", monospace;
  font-weight: 600;
  /*color: #504da6;*/
}

code {
  padding: 2px 4px;
  color: #444444;
  white-space: nowrap;
  background-color: white;
  border: 1px solid #777777; }

pre {
  display: inline-block;
  box-sizing: border-box;
  min-width: calc(100% - 19.5px);
  padding: 9.5px;
  margin: 0.25em 10px 0.25em 10px;
  font-size: 14px;
  line-height: 20px;
  white-space: pre !important;
  overflow-y: hidden;
  overflow-x: visible;
  background-color: whitesmoke;
  border: 1px solid #cccccc;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  border-radius: 4px; }

pre.prettyprint {
  margin-bottom: 20px; }

pre code {
  padding: 0;
  color: inherit;
  white-space: pre;
  overflow-x: visible;
  background-color: transparent;
  border: 0; }

.pre-scrollable {
  max-height: 340px;
  overflow-y: scroll; }

table {
  max-width: 100%;
  background-color: transparent;
  border-collapse: collapse;
  border-spacing: 0; }

table th, table td {
  padding: 0px 8px 0px;
}

.table {
  width: 100%;
  margin-bottom: 20px; }

.table th,
.table td {
  padding: 8px;
  line-height: 20px;
  text-align: left;
  vertical-align: top;
  border-top: 1px solid #444444; }

.table th {
  font-weight: bold; }

.table thead th {
  vertical-align: bottom; }

.table caption + thead tr:first-child th,
.table caption + thead tr:first-child td,
.table colgroup + thead tr:first-child th,
.table colgroup + thead tr:first-child td,
.table thead:first-child tr:first-child th,
.table thead:first-child tr:first-child td {
  border-top: 0; }

.table tbody + tbody {
  border-top: 2px solid #444444; }

.table .table {
  background-color: rgba(252, 248, 244, 0.75); }

.table-condensed th,
.table-condensed td {
  padding: 4px 5px; }

.table-bordered {
  border: 1px solid #444444;
  border-collapse: separate;
  *border-collapse: collapse;
  border-left: 0;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  border-radius: 4px; }

.table-bordered th,
.table-bordered td {
  border-left: 1px solid #444444; }

.table-bordered caption + thead tr:first-child th,
.table-bordered caption + tbody tr:first-child th,
.table-bordered caption + tbody tr:first-child td,
.table-bordered colgroup + thead tr:first-child th,
.table-bordered colgroup + tbody tr:first-child th,
.table-bordered colgroup + tbody tr:first-child td,
.table-bordered thead:first-child tr:first-child th,
.table-bordered tbody:first-child tr:first-child th,
.table-bordered tbody:first-child tr:first-child td {
  border-top: 0; }

.table-bordered thead:first-child tr:first-child > th:first-child,
.table-bordered tbody:first-child tr:first-child > td:first-child,
.table-bordered tbody:first-child tr:first-child > th:first-child {
  -webkit-border-top-left-radius: 4px;
  border-top-left-radius: 4px;
  -moz-border-radius-topleft: 4px; }

.table-bordered thead:first-child tr:first-child > th:last-child,
.table-bordered tbody:first-child tr:first-child > td:last-child,
.table-bordered tbody:first-child tr:first-child > th:last-child {
  -webkit-border-top-right-radius: 4px;
  border-top-right-radius: 4px;
  -moz-border-radius-topright: 4px; }

.table-bordered thead:last-child tr:last-child > th:first-child,
.table-bordered tbody:last-child tr:last-child > td:first-child,
.table-bordered tbody:last-child tr:last-child > th:first-child,
.table-bordered tfoot:last-child tr:last-child > td:first-child,
.table-bordered tfoot:last-child tr:last-child > th:first-child {
  -webkit-border-bottom-left-radius: 4px;
  border-bottom-left-radius: 4px;
  -moz-border-radius-bottomleft: 4px; }

.table-bordered thead:last-child tr:last-child > th:last-child,
.table-bordered tbody:last-child tr:last-child > td:last-child,
.table-bordered tbody:last-child tr:last-child > th:last-child,
.table-bordered tfoot:last-child tr:last-child > td:last-child,
.table-bordered tfoot:last-child tr:last-child > th:last-child {
  -webkit-border-bottom-right-radius: 4px;
  border-bottom-right-radius: 4px;
  -moz-border-radius-bottomright: 4px; }

.table-bordered tfoot + tbody:last-child tr:last-child td:first-child {
  -webkit-border-bottom-left-radius: 0;
  border-bottom-left-radius: 0;
  -moz-border-radius-bottomleft: 0; }

.table-bordered tfoot + tbody:last-child tr:last-child td:last-child {
  -webkit-border-bottom-right-radius: 0;
  border-bottom-right-radius: 0;
  -moz-border-radius-bottomright: 0; }

.table-bordered caption + thead tr:first-child th:first-child,
.table-bordered caption + tbody tr:first-child td:first-child,
.table-bordered colgroup + thead tr:first-child th:first-child,
.table-bordered colgroup + tbody tr:first-child td:first-child {
  -webkit-border-top-left-radius: 4px;
  border-top-left-radius: 4px;
  -moz-border-radius-topleft: 4px; }

.table-bordered caption + thead tr:first-child th:last-child,
.table-bordered caption + tbody tr:first-child td:last-child,
.table-bordered colgroup + thead tr:first-child th:last-child,
.table-bordered colgroup + tbody tr:first-child td:last-child {
  -webkit-border-top-right-radius: 4px;
  border-top-right-radius: 4px;
  -moz-border-radius-topright: 4px; }

table.docutils th {
  background-color: #e8e8e8; }

table.docutils tr:hover {
  background-color: whitesmoke; }

.table-striped tbody > tr:nth-child(odd) > td,
.table-striped tbody > tr:nth-child(odd) > th {
  background-color: rgba(252, 248, 244, 0.75); }

.table-hover tbody tr:hover > td,
.table-hover tbody tr:hover > th {
  background-color: rgba(241, 222, 204, 0.75); }

table td[class*="span"],
table th[class*="span"],
.row-fluid table td[class*="span"],
.row-fluid table th[class*="span"] {
  display: table-cell;
  float: none;
  margin-left: 0; }

.hero-unit {
  padding: 60px;
  margin-bottom: 30px;
  font-size: 18px;
  font-weight: 200;
  line-height: 30px;
  color: inherit;
  background-color: rgba(230, 197, 164, 0.75);
  -webkit-border-radius: 6px;
  -moz-border-radius: 6px;
  border-radius: 6px; }

.hero-unit h1 {
  margin-bottom: 0;
  font-size: 60px;
  line-height: 1;
  letter-spacing: -1px;
  color: inherit; }

.hero-unit li {
  line-height: 30px; }

/* rst2html default used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0; }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 !important; }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 !important; }

.last, .with-subtitle {
  margin-bottom: 0 !important; }

.hidden {
  display: none; }

a.toc-backref {
  text-decoration: none;
  color: #444444; }

blockquote.epigraph {
  margin: 2em 5em; }

dl.docutils dd {
  margin-bottom: 0.5em; }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden; }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/
div.abstract {
  margin: 2em 5em; }

div.abstract p.topic-title {
  font-weight: bold;
  text-align: center; }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em;
  border: medium outset;
  padding: 1em; }

div.note, div.warning {
  margin: 1.5em 0px;
  border: none; }

div.note p.admonition-title,
div.warning p.admonition-title {
  display: none; }

/* Clearfix
 * http://css-tricks.com/snippets/css/clear-fix/
 */
div.note:after,
div.warning:after {
  content: "";
  display: table;
  clear: both; }

div.note p:before,
div.warning p:before {
  display: block;
  float: left;
  font-size: 4em;
  line-height: 1em;
  margin-right: 20px;
  margin-left: 0em;
  margin-top: -10px;
  content: '\0270D';
  /*handwriting*/ }

div.warning p:before {
  content: '\026A0';
  /*warning*/ }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold;
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif; }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
  color: #b30000;
  font-weight: bold;
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif; }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/
div.dedication {
  margin: 2em 5em;
  text-align: center;
  font-style: italic; }

div.dedication p.topic-title {
  font-weight: bold;
  font-style: normal; }

div.figure {
  margin-left: 2em;
  margin-right: 2em; }

div.footer, div.header {
  clear: both;
  font-size: smaller; }

div.line-block {
  display: block;
  margin-top: 1em;
  margin-bottom: 1em; }

div.line-block div.line-block {
  margin-top: 0;
  margin-bottom: 0;
  margin-left: 1.5em; }

div.sidebar {
  margin: 0 0 0.5em 1em;
  border: medium outset;
  padding: 1em;
  background-color: rgba(252, 248, 244, 0.75);
  width: 40%;
  float: right;
  clear: right; }

div.sidebar p.rubric {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-size: medium; }

div.system-messages {
  margin: 5em; }

div.system-messages h1 {
  color: #b30000; }

div.system-message {
  border: medium outset;
  padding: 1em; }

div.system-message p.system-message-title {
  color: #b30000;
  font-weight: bold; }

div.topic {
  margin: 2em; }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em; }

h1.title {
  text-align: center; }

h2.subtitle {
  text-align: center; }

hr.docutils {
  width: 75%; }

img.align-left, .figure.align-left, object.align-left {
  clear: left;
  float: left;
  margin-right: 1em; }

img.align-right, .figure.align-right, object.align-right {
  clear: right;
  float: right;
  margin-left: 1em; }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto; }

.align-left {
  text-align: left; }

.align-center {
  clear: both;
  text-align: center; }

.align-right {
  text-align: right; }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit; }

/* div.align-center * { */
/*   text-align: left } */

ul.simple > li {
  margin-bottom: 0.5em }

ol.simple, ul.simple {
  margin-bottom: 1em; }

ol.arabic {
  list-style: decimal; }

ol.loweralpha {
  list-style: lower-alpha; }

ol.upperalpha {
  list-style: upper-alpha; }

ol.lowerroman {
  list-style: lower-roman; }

ol.upperroman {
  list-style: upper-roman; }

p.attribution {
  text-align: right;
  margin-left: 50%; }

p.caption {
  font-style: italic; }

p.credits {
  font-style: italic;
  font-size: smaller; }

p.label {
  white-space: nowrap; }

p.rubric {
  font-weight: bold;
  font-size: larger;
  color: maroon;
  text-align: center; }

p.sidebar-title {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-weight: bold;
  font-size: larger; }

p.sidebar-subtitle {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-weight: bold; }

p.topic-title {
  font-weight: bold; }

pre.address {
  margin-bottom: 0;
  margin-top: 0;
  font: inherit; }

pre.literal-block, pre.doctest-block, pre.math, pre.code {
  margin-left: 2em;
  margin-right: 2em; }

pre.code .ln {
  color: grey; }

/* line numbers */
pre.code, code {
  background-color: #eeeeee; }

pre.code .comment, code .comment {
  color: #5c6576; }

pre.code .keyword, code .keyword {
  color: #3B0D06;
  font-weight: bold; }

pre.code .literal.string, code .literal.string {
  color: #0c5404; }

pre.code .name.builtin, code .name.builtin {
  color: #352b84; }

pre.code .deleted, code .deleted {
  background-color: #DEB0A1; }

pre.code .inserted, code .inserted {
  background-color: #A3D289; }

span.classifier {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-style: oblique; }

span.classifier-delimiter {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif;
  font-weight: bold; }

span.interpreted {
  font-family: "Helvetica Neue", "HelveticaNeue", "Raleway", Helvetica, Arial, sans-serif; }

span.option {
  white-space: nowrap; }

span.pre {
  white-space: pre; }

span.problematic {
  color: #b30000; }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80%; }

table.citation {
  border-left: solid 1px #666666;
  margin-left: 1px; }

table.docinfo {
  margin: 0em;
  margin-top: 2em;
  margin-bottom: 2em;
  font-family: "Raleway", "Helvetica Neue", "HelveticaNeue", Helvetica, Arial, sans-serif !important;
  color: #444444; }

table.docutils {
  margin-top: 0.5em;
  margin-bottom: 0.5em; }

table.footnote {
  border-left: solid 1px #2d2d2d;
  margin-left: 1px; }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em;
  padding-right: 0.5em;
  vertical-align: top; }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: 700;
  text-align: left;
  white-space: nowrap;
  padding-left: 0; }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100%; }

ul.auto-toc {
  list-style-type: none; }

span.DecNumber {
  color: #252dbe; }

span.BinNumber {
  color: #252dbe; }

span.HexNumber {
  color: #252dbe; }

span.OctNumber {
  color: #252dbe; }

span.FloatNumber {
  color: #252dbe; }

span.Identifier {
  color: #3b3b3b; }

span.Keyword {
  font-weight: 600;
  color: #5e8f60; }

span.StringLit {
  color: #a4255b; }

span.LongStringLit {
  color: #a4255b; }

span.CharLit {
  color: #a4255b; }

span.EscapeSequence {
  color: black; }

span.Operator {
  color: black; }

span.Punctuation {
  color: black; }

span.Comment, span.LongComment {
  font-style: italic;
  font-weight: 400;
  color: #484a86; }

span.RegularExpression {
  color: darkviolet; }

span.TagStart {
  color: darkviolet; }

span.TagEnd {
  color: darkviolet; }

span.Key {
  color: #252dbe; }

span.Value {
  color: #252dbe; }

span.RawData {
  color: #a4255b; }

span.Assembler {
  color: #252dbe; }

span.Preprocessor {
  color: #252dbe; }

span.Directive {
  color: #252dbe; }

span.Command, span.Rule, span.Hyperlink, span.Label, span.Reference,
span.Other {
  color: black; }

/* Pop type, const, proc, and iterator defs in nim def blocks */
dt pre > span.Identifier, dt pre > span.Operator {
  color: #155da4;
  font-weight: 700; }

dt pre > span.Identifier ~ span.Identifier, dt pre > span.Operator ~ span.Identifier {
  color: inherit;
  font-weight: inherit; }

dt pre > span.Operator ~ span.Identifier, dt pre > span.Operator ~ span.Operator {
  color: inherit;
  font-weight: inherit; }

/* Nim sprite for the footer (taken from main page favicon) */
.nim-sprite {
  display: inline-block;
  height: 12px;
  width: 12px;
  background-position: 0 0;
  background-size: 12px 12px;
  -webkit-filter: opacity(50%);
  background-repeat: no-repeat;
  background-image: url("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==");
  margin-bottom: -5px; }
  div.pragma {
    display: none;
  }
  span.pragmabegin {
    cursor: pointer;
  }
  span.pragmaend {
    cursor: pointer;
  }

div.search_results {
  background-color: antiquewhite;
  margin: 3em;
  padding: 1em;
  border: 1px solid #4d4d4d;
}
</style>

<script type="text/javascript" src="../dochack.js"></script>

<script type="text/javascript">
function togglepragma(d) {
  if (d.style.display != 'inline')
    d.style.display = 'inline';
  else
    d.style.display = 'none';
}

function main() {
  var elements = document.getElementsByClassName("pragmabegin");
  for (var i = 0; i < elements.length; ++i) {
    var e = elements[i];
    e.onclick = function(event) {
      togglepragma(event.target.nextSibling);
    };
  }
  var elements = document.getElementsByClassName("pragmaend");
  for (var i = 0; i < elements.length; ++i) {
    var e = elements[i];
    e.onclick = function(event) {
      togglepragma(event.target.previousSibling);
    };
  }
}
</script>

</head>
<body onload="main()">
<div class="document" id="documentId">
  <div class="container">
    <h1 class="title">Nim DocGen Tools Guide</h1>
    <div class="row">
  <div class="three columns">
  <div>
    Search: <input type="text" id="searchInput"
      onkeyup="search()" />
  </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-documentation-comments_toc" href="#introduction-documentation-comments">Documentation Comments</a></li>
<li><a class="reference" id="introduction-nim-file-input_toc" href="#introduction-nim-file-input">Nim file input</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-html_toc" href="#document-types-html">HTML</a></li>
<li><a class="reference" id="document-types-json_toc" href="#document-types-json">JSON</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-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">
  <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> 0.16.0</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 and JSON output from input .nim files and projects, as well as HTML and LaTeX from input RST (reStructuredText) files. The output documentation will include module dependencies (<tt class="docutils literal"><span class="pre">import</span></tt>), any top-level documentation comments (##), and exported symbols (*), including procedures, types, and variables.</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 (##), are interpreted as documentation.  Comments are parsed as RST (see <a class="reference external" href="http://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.</p>
<p>Example:</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>Outputs:<pre>Person* = object
  name: string
  age: int</pre>
</p>
<p>This type contains a description of a person</p>
<p>Field documentation comments can be added to fields like so:</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>Note that without the <cite>*</cite> 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>

<h2><a class="toc-backref" id="introduction-nim-file-input" href="#introduction-nim-file-input">Nim file input</a></h2><p>The following examples will generate documentation for the below contrived <em>Nim</em> module, aptly named 'sample.nim'</p>
<p>sample.nim:</p>
<pre class = "listing"><span class="Comment">## This module is a sample.</span>

<span class="Keyword">import</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 &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="Identifier">helloWorld</span><span class="Punctuation">(</span><span class="DecNumber">5</span><span class="Punctuation">)</span></pre>
<h1><a class="toc-backref" id="document-types" href="#document-types">Document Types</a></h1>
<h2><a class="toc-backref" id="document-types-html" href="#document-types-html">HTML</a></h2><p>Generation of HTML documents is done via both the <tt class="docutils literal"><span class="pre">doc</span></tt> and <tt class="docutils literal"><span class="pre">doc2</span></tt> commands. These command take either a single .nim file, outputting a single .html file with the same base filename, or multiple .nim files, outputting multiple .html files and, optionally, an index file.</p>
<p>The <tt class="docutils literal"><span class="pre">doc</span></tt> command:<pre>nim doc sample</pre>
</p>
<p>Partial Output:<pre>...
proc helloWorld*(times: int)
...</pre>
</p>
<p>Output can be viewed in full here: <a class="reference external" href="docgen_sample.html">docgen_sample.html</a>. The next command, called <tt class="docutils literal"><span class="pre">doc2</span></tt>, is very similar to the <tt class="docutils literal"><span class="pre">doc</span></tt> command, but will be run after the compiler performs semantic checking on the input nim module(s), which allows it to process macros.</p>
<p>The <tt class="docutils literal"><span class="pre">doc2</span></tt> command:<pre>nim doc2 sample</pre>
</p>
<p>Partial Output:<pre>...
proc helloWorld(times: int) {.raises: [], tags: [].}
...</pre>
</p>
<p>The full output can be seen here: <a class="reference external" href="docgen_sample2.html">docgen_sample2.html</a>. As you can see, the tool has extracted additional information provided to it by the compiler beyond what the <tt class="docutils literal"><span class="pre">doc</span></tt> command provides, such as pragmas attached implicitly by the compiler. This type of information is not available from looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the <tt class="docutils literal"><span class="pre">doc</span></tt> command does.</p>

<h2><a class="toc-backref" id="document-types-json" href="#document-types-json">JSON</a></h2><p>Generation of JSON documents is done via the <tt class="docutils literal"><span class="pre">jsondoc</span></tt> command. This command takes in a .nim file, and outputs a .json file with the same base filename. Note that this tool is built off of the <tt class="docutils literal"><span class="pre">doc</span></tt> command, and therefore is performed before semantic checking.</p>
<p>The <tt class="docutils literal"><span class="pre">jsondoc</span></tt> command:<pre>nim jsondoc sample</pre>
</p>
<p>Output:<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>

<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><pre>nim doc2 --project filename.nim</pre>
<p>This will recursively generate documentation of all nim modules imported into the input module, including system modules. Be careful with this command, as it may end up sprinkling html files all over your filesystem!</p>

<h2><a class="toc-backref" id="related-options-index-switch" href="#related-options-index-switch">Index switch</a></h2><pre>nim doc2 --index:on filename.nim</pre>
<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 external" href="#index-idx-file-format">Index (idx) file format</a> section for details.</p>
<p>Once index files have been generated for one or more modules, the Nim compiler command <tt class="docutils literal"><span class="pre">buildIndex directory</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>

<h2><a class="toc-backref" id="related-options-see-source-switch" href="#related-options-see-source-switch">See source switch</a></h2><pre>nim doc2 --docSeeSrcUrl:txt filename.nim</pre>
<p>When you pass the <tt class="docutils literal"><span class="pre">docSeeSrcUrl</span></tt> switch to docgen, after each documented item in your source code the hyper link <em>See source</em> will appear 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>If you want to reuse this feature in your own documentation you will have to modify <tt class="docutils literal"><span class="pre">config/nimdoc.cfg</span></tt> to contain a <tt class="docutils literal"><span class="pre">doc.item.seesrc</span></tt> value with a hyper link to your own code repository. As you will see by the comments in that file, the value <tt class="docutils literal"><span class="pre">txt</span></tt> passed on the command line will be used in the HTML template along others like <tt class="docutils literal"><span class="pre">$path</span></tt> and <tt class="docutils literal"><span class="pre">$line</span></tt>.</p>
<p>In the case of Nim's own documentation, the <tt class="docutils literal"><span class="pre">txt</span></tt> value is just a commit hash to append to a formatted URL to <a class="reference external" href="https://github.com/Araq/Nim">https://github.com/Araq/Nim</a>. The <tt class="docutils literal"><span class="pre">tools/nimweb.nim</span></tt> helper queries the current git commit hash during doc generation, but since you might be working on an unpublished repository, it also allows specifying a <tt class="docutils literal"><span class="pre">githash</span></tt> value in <tt class="docutils literal"><span class="pre">web/website.ini</span></tt> to force a specific commit in the output.</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">rst2html</span></tt> and <tt class="docutils literal"><span class="pre">rst2tex</span></tt> commands. Documents like this one are initially written in a dialect of RST which adds support for nim sourcecode 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 C++ and some other c-like languages.</p>
<p>Usage:<pre>nim rst2html docgen.txt</pre>
</p>
<p>Output:<pre>You're reading it!</pre>
</p>
<p>The input can be viewed here <a class="reference external" href="docgen.txt">docgen.txt</a>. The <tt class="docutils literal"><span class="pre">rst2tex</span></tt> command is invoked identically to <tt class="docutils literal"><span class="pre">rst2html</span></tt>, but outputs a .tex file instead of .html.</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">rst2html</span></tt> command, all sections in the RST document will get an anchor you can hyper link 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">doc</span></tt> or <tt class="docutils literal"><span class="pre">doc2</span></tt> commands 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 which works unless you have a module with collisions due to overloading.</p>
<p>If you hyper link 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 from several parts:</p>
<blockquote><p>(<strong>plain symbol</strong>)(<strong>.type</strong>),(<strong>first param</strong>)?(<strong>,param type</strong>)*</p></blockquote>
<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>proc</td><td><em>empty string</em></td></tr>
<tr><td>macro</td><td><tt class="docutils literal"><span class="pre">.m</span></tt></td></tr>
<tr><td>method</td><td><tt class="docutils literal"><span class="pre">.e</span></tt></td></tr>
<tr><td>iterator</td><td><tt class="docutils literal"><span class="pre">.i</span></tt></td></tr>
<tr><td>template</td><td><tt class="docutils literal"><span class="pre">.t</span></tt></td></tr>
<tr><td>converter</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">complexName</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">type SignedInt = int | int8 | int16 | int32 | int64</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#SignedInt">#SignedInt</a></li>
<li><tt class="docutils literal"><span class="pre">var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#globalRaiseHook">#globalRaiseHook</a></li>
<li><tt class="docutils literal"><span class="pre">const NimVersion = &quot;0.0.0&quot;</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#NimVersion">#NimVersion</a></li>
<li><tt class="docutils literal"><span class="pre">proc getTotalMem(): int {.rtl, raises: [], tags: [].}</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#getTotalMem,">#getTotalMem,</a></li>
<li><tt class="docutils literal"><span class="pre">proc len[T](x: seq[T]): int {.magic: &quot;LengthSeq&quot;, noSideEffect.}</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">iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#pairs.i,seq[T]">#pairs.i,seq[T]</a></li>
<li><tt class="docutils literal"><span class="pre">template newException[](exceptn: typedesc; message: string): expr</span></tt> <strong>=&gt;</strong> <a class="reference external" href="system.html#newException.t,typedesc,string">#newException.t,typedesc,string</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 external" href="#index-switch">Index switch</a> along with commands to generate documentation from source or text files. You can programatically generate indices with the <a class="reference external" href="rstgen.html#setIndexTerm">setIndexTerm()</a> and <a class="reference external" href="rstgen.html#writeIndexFile">writeIndexFile()</a> procs. The purpose of <tt class="docutils literal"><span class="pre">idx</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">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 at least two fields, but can have up to four (additional columns are ignored). The content of these columns is:</p>
<ol class="simple"><li>Mandatory term being indexed. Terms can include quoting according to Nim's rules (eg. `^` like in <a class="reference external" href="actors.html#^,ptr.TChannel[T]">the actors module</a>).</li>
<li>Base filename plus anchor hyper link (eg. <tt class="docutils literal"><span class="pre">algorithm.html#*,int,SortOrder</span></tt>).</li>
<li>Optional human readable string to display as hyper link. If the value is not present or is the empty string, the hyper link 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 hyper link. Browsers usually display this as a tooltip after hovering a moment over the hyper link.</li>
</ol>
<p>The index generation tools try to 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">.txt</span></tt> or <tt class="docutils literal"><span class="pre">.rst</span></tt> files. The former are always closely related to source code and consist mainly of API entries. The latter are generic documents meant for human reading.</p>
<p>To differentiate both types (documents and APIs), the index generator will add to the index of documents an entry with the title of the document. Since the title is the topmost element, it will be added with a second field containing just the filename without any HTML anchor.  By convention this entry without anchor is the <em>title entry</em>, and since entries in the index file are added as they are scanned, the title entry will be the first line. The title for APIs is not present because it can be generated concatenating the name of the file to the word <strong>Module</strong>.</p>
<p>Normal symbols are added to the index with surrounding whitespaces removed. An exception to this are table of content (TOC) entries. TOC entries are added to the index file with their third column having as much prefix spaces as their level is in the TOC (at least 1 character). The prefix whitespace helps to filter TOC entries from API or text symbols. This is important because the amount of spaces is used to replicate the hiearchy for document TOCs in the final index, and TOC entries found in <tt class="docutils literal"><span class="pre">.nim</span></tt> files are discarded.</p>

<h1><a class="toc-backref" id="additional-resources" href="#additional-resources">Additional resources</a></h1><p><a class="reference external" href="nimc.html#command-line-switches">Nim Compiler User Guide</a></p>
<p><a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">RST Quick Reference</a></p>
<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 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="row">
      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br/>
        <small>Made with Nim. Generated: 2017-01-09 23:41:29 UTC</small>
      </div>
    </div>
  </div>
</div>

</body>
</html>
nim-doc 0.16.0-1 / usr / share / doc / nim-doc / html / docgen.html
