mirror of
https://github.com/nim-lang/Nim.git
synced 2026-09-17 10:34:53 +00:00
4cf3a95554
This PR adds a new Nim compiler command and introduces some improvements to the docgen suite in general. 1. Adds `nim book`, the new command that takes a directory with Markdown/ReST files and generates a navigatable, searchable, Nim-first documentation site. 2. Refactors the default nimdoc.cfg, specifically the part marked with "needs to be refactored." Code duplication was removed, new overridable variables were added, quirky logic with the "Group by" switch display was fixed. Here's a live demo of a `nim book` produced book: https://moigagoo.github.io/nim-chronos/ The original mdBook-powered version: https://status-im.github.io/nim-chronos/ Related to this PR but valuable on their own: 1. `.. include::` directive has received several improvements: - You can now include code from line to line, merged: https://github.com/nim-lang/Nim/pull/26130 - You can now include code with syntax highlighting, merged: https://github.com/nim-lang/Nim/pull/26146 2. `.. admonition::` directive (and its derivatives like `warning`, `error`, etc.) got new useful functions: - You can now set a title to your admonitions, open: https://github.com/nim-lang/Nim/pull/26159 - You can make admonitions collapsible (useful when you need to include a large chunk if code), open: https://github.com/nim-lang/Nim/pull/26159
128 lines
11 KiB
HTML
128 lines
11 KiB
HTML
<?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>Welcome to Nim Book</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">
|
|
|
|
<!-- JS -->
|
|
<script type="text/javascript" src="dochack.js"></script>
|
|
</head>
|
|
<body>
|
|
<div class="document" id="documentId">
|
|
<input type="checkbox" id="nav-toggle" hidden>
|
|
<label for="nav-toggle" id="nav-burger">☰</label>
|
|
<label for="nav-toggle" id="nav-overlay"></label>
|
|
<div class="container">
|
|
<h1 class="title">Welcome to Nim Book</h1>
|
|
<div class="row">
|
|
<div class="three columns">
|
|
<div class="theme-select-wrapper">
|
|
<label for="theme-select">Theme: </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 simple-toc-section"><li><a href="intro.html" class="current">Intro</a></li><li><a href="page1.html" class="">Page 1</a></li><li><strong>Section 1</strong></li><li><a href="sections/1/intro.html" class="">Intro</a></li><li><details><summary><a href="sections/1/page2.html" class="">Page 2</a></summary><ul class="simple nested-toc-section"><li><a href="sections/1/page2/subpage1.html" class="">Subpage 1</a></li></ul></details></li><li><details><summary>Section 2</summary><ul class="simple nested-toc-section"><li><a href="sections/2/intro.html" class="">Intro</a></li><li><details><summary><a href="sections/2/page3.html" class="">Page 3</a></summary><ul class="simple nested-toc-section"><li><a href="sections/2/page3/subpage2.html" class="">Subpage 2</a></li></ul></details></li></ul></details></li><li><a href="./api/theindex.html" class="">API docs</a></li><li><a href="https://nim-lang.org" class="">nim-lang.org</a></li><li><a href="./nosuchpage.md" class="">Four-oh-four</a></li></ul>
|
|
<ul class="simple">
|
|
<li><a id="indexLink" href="theindex.html">Index</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
<div id="searchInputDiv">
|
|
Search: <input type="search" id="searchInput" oninput="search()"/>
|
|
</div>
|
|
|
|
|
|
<ul class="simple simple-toc" id="toc-list">
|
|
<li><a class="reference" id="code_toc" href="#code">Code</a></li>
|
|
<li><a class="reference" id="admonitions_toc" href="#admonitions">Admonitions</a></li>
|
|
<li><a class="reference" id="links_toc" href="#links">Links</a></li>
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
<div class="nine columns" id="content">
|
|
|
|
<div id="tocRoot"></div>
|
|
|
|
<p class="module-desc"><p>This is a test project for <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">book</span></span></tt>.</p>
|
|
|
|
<h1><a class="toc-backref" id="code" href="#code">Code</a></h1><p>Inline code snippet:</p>
|
|
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">twice</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="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
|
|
<span class="Identifier">a</span> <span class="Operator">*</span> <span class="DecNumber">2</span></pre></p>
|
|
<p>This snippet is tested during documentation build:</p>
|
|
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">twice</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="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
|
|
<span class="Identifier">a</span> <span class="Operator">*</span> <span class="DecNumber">2</span>
|
|
|
|
<span class="Identifier">assert</span> <span class="FloatNumber">10.</span><span class="Identifier">twice</span> <span class="Operator">==</span> <span class="DecNumber">20</span></pre></p>
|
|
<p>The same but using <tt class="docutils literal"><span class="pre">.. code::</span></tt> directive:</p>
|
|
<pre class="listing">proc twice*(a: int): int =
|
|
a * 2</pre><pre class="listing">proc twice*(a: int): int =
|
|
a * 2
|
|
|
|
assert 10.twice == 20</pre><p>Code included from a source file:</p>
|
|
<pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">double</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
|
|
<span class="Identifier">x</span> <span class="Operator">*</span> <span class="DecNumber">2</span>
|
|
</pre><p>Selective inclusuion:</p>
|
|
<pre class="listing">
|
|
<span class="Keyword">proc</span> <span class="Identifier">double</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
|
|
<span class="Identifier">x</span> <span class="Operator">*</span> <span class="DecNumber">2</span>
|
|
</pre><p>Doesn't have to be Nim code:</p>
|
|
<pre class="listing"><span class="Comment"># This is Python</span>
|
|
<span class="Keyword">def</span> <span class="Identifier">double</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">-></span> <span class="Identifier">int</span><span class="Punctuation">:</span>
|
|
<span class="Keyword">return</span> <span class="Identifier">x</span> <span class="Operator">*</span> <span class="DecNumber">2</span>
|
|
</pre>
|
|
<h1><a class="toc-backref" id="admonitions" href="#admonitions">Admonitions</a></h1><div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
|
|
General info</div>
|
|
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
|
|
<p>It's dangerous to go alone!</p>
|
|
<p>Take this!</p>
|
|
</div>
|
|
<div class="admonition admonition-error"><span class="admonition-error-text"><b>Error:</b></span>
|
|
Oh, snap :-(</div>
|
|
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Important:</b></span>
|
|
Admonitions can contain lists and code blocks.<ul class="simple"><li>This</li>
|
|
<li>is</li>
|
|
<li>great!</li>
|
|
</ul>
|
|
<pre class="listing"><span class="Identifier">echo</span> <span class="StringLit">"Indeed"</span></pre></div>
|
|
|
|
<h1><a class="toc-backref" id="links" href="#links">Links</a></h1><p>This is a link to a heading on the same page: <a class="reference internal" href="#code">Code</a>.</p>
|
|
<p>This is a link to a heading on another page: <a class="reference external" href="sections/1/intro.html#heading">intro.md: Heading</a>.</p>
|
|
<p>Same, but with different syntax: <a class="reference external" href="sections/1/intro.html#heading">intro.md: Heading</a>.</p>
|
|
<p>You can use standard Markdown syntax, too: <a class="reference external" href="page1.html#heading">I am a link</a> </p>
|
|
</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="twelve-columns footer">
|
|
<span class="nim-sprite"></span>
|
|
<br>
|
|
<small style="color: var(--hint);">Made with Nim. Generated: 1970-01-02 03:46:40 UTC</small>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|