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
246 lines
9.9 KiB
INI
246 lines
9.9 KiB
INI
# This is the config file for the documentation generator.
|
|
# (c) 2016 Andreas Rumpf
|
|
# Feel free to edit the templates as you need. If you modify this file, it
|
|
# might be worth updating the hardcoded values in packages/docutils/rstgen.nim
|
|
|
|
split.item.toc = "20"
|
|
# too long entries in the table of contents wrap around
|
|
# after this number of characters
|
|
|
|
doc.section = """
|
|
<div class="section" id="$sectionID">
|
|
<h1><a class="toc-backref" href="#$sectionID">$sectionTitle</a></h1>
|
|
<dl class="item">
|
|
$content
|
|
</dl>
|
|
</div>
|
|
"""
|
|
|
|
# Just a single item in the TOC (e.g. imports, exports)
|
|
doc.section.toc_item = """
|
|
<li>
|
|
<a class="reference reference-toplevel" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a>
|
|
</li>
|
|
"""
|
|
|
|
# This is a section (e.g. procs, types) in the TOC which gets turned into a drop down
|
|
doc.section.toc = """
|
|
<li>
|
|
<details open>
|
|
<summary><a class="reference reference-toplevel" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a></summary>
|
|
<ul class="simple simple-toc-section">
|
|
$content
|
|
</ul>
|
|
</details>
|
|
</li>
|
|
"""
|
|
|
|
doc.section.toc2 = """
|
|
<ul class="simple nested-toc-section">$plainName
|
|
$content
|
|
</ul>
|
|
"""
|
|
|
|
# Chunk of HTML emitted for each entry in the HTML table of contents.
|
|
# Available variables are:
|
|
# * $desc: the actual docstring of the item.
|
|
# * $header: the full version of name, including types, pragmas, tags, etc.
|
|
# * $header_plain: like header but without HTML (and without pragmas, tags, etc.),
|
|
# for attribute embedding.
|
|
# * $itemID: numerical unique entry of the item in the HTML.
|
|
# * $itemSym: short symbolic name of the item for easier hyperlinking.
|
|
# * $itemSymEnc: quoted version for URLs or attributes.
|
|
# * $itemSymOrID: the symbolic name or the ID if that is not unique.
|
|
# * $itemSymOrIDEnc: quoted version for URLs or attributes.
|
|
# * $name: reduced name of the item.
|
|
# * $uniqueName: name with parameters for routine types or $name for others.
|
|
# * $seeSrc: generated HTML from doc.item.seesrc (if some switches are used).
|
|
|
|
doc.item = """
|
|
<div id="$itemSymOrID">
|
|
<dt><pre>$header</pre></dt>
|
|
<dd>
|
|
$deprecationMsg
|
|
$desc
|
|
$seeSrc
|
|
</dd>
|
|
</div>
|
|
"""
|
|
|
|
# A wrapper of a few overloaded `doc.item`s with the same basic name
|
|
# * $header_plain - see above
|
|
# * $overloadGroupName - the anchor for this whole group
|
|
# * $content - string containing `doc.item`s themselves
|
|
doc.item2 = """
|
|
<div id="$overloadGroupName">
|
|
$content
|
|
</div>
|
|
"""
|
|
|
|
# Chunk of HTML emitted for each entry in the HTML table of contents.
|
|
# See doc.item for available substitution variables.
|
|
|
|
# This is used for TOC items which are not overloadable (e.g. types).
|
|
# `$header_plain` would be too verbose here, so we use $name.
|
|
doc.item.toc = """
|
|
<li><a class="reference" href="#$itemSymOrIDEnc" title="$header_plain">$name</a></li>
|
|
"""
|
|
|
|
# This is used for TOC items which are grouped by the same name (e.g. procs).
|
|
doc.item.tocTable = """
|
|
<li><a class="reference" href="#$itemSymOrIDEnc" title="$header_plain">$header_plain</a></li>
|
|
"""
|
|
|
|
# HTML rendered for doc.item's seeSrc variable. Note that this will render to
|
|
# the empty string if you don't pass anything through --git.url. Available
|
|
# substitutaion variables here are:
|
|
# * $commit: branch/commit to use in source link.
|
|
# * $devel: branch to use in edit link.
|
|
# * $path: relative path to the file being processed.
|
|
# * $line: line of the item in the original source file.
|
|
# * $url: whatever you did pass through the --git.url switch (which also
|
|
# gets variables path/line replaced!)
|
|
doc.item.seesrc = """
|
|
<a href="${url}/tree/${commit}/${path}#L${line}" class="link-seesrc" target="_blank">Source</a>
|
|
<a href="${url}/edit/${devel}/${path}#L${line}" class="link-seesrc" target="_blank" >Edit</a>
|
|
"""
|
|
|
|
doc.deprecationmsg = """
|
|
<div class="deprecation-message">
|
|
<b>$label</b> $message
|
|
</div>
|
|
"""
|
|
|
|
doc.toc = """
|
|
<ul class="simple simple-toc" id="toc-list">
|
|
$content
|
|
</ul>
|
|
"""
|
|
|
|
doc.body_toc_groupsection = """
|
|
<div class="search-groupby">
|
|
Group by:
|
|
<select onchange="groupBy(this.value)">
|
|
<option value="section">Section</option>
|
|
<option value="type">Type</option>
|
|
</select>
|
|
</div>
|
|
"""
|
|
|
|
doc.body_toc_themeselect = """
|
|
<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>
|
|
"""
|
|
|
|
doc.body_toc_indexlink = """
|
|
<ul class="simple">
|
|
<li><a id="indexLink" href="$theindexhref">Index</a></li>
|
|
</ul>
|
|
"""
|
|
|
|
doc.body_toc_searchbox = """
|
|
<div id="searchInputDiv">
|
|
Search: <input type="search" id="searchInput" oninput="search()"/>
|
|
</div>
|
|
"""
|
|
|
|
@if boot:
|
|
doc.body_toc_globallinks = """
|
|
<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="$theindexhref">Index</a></li>
|
|
<li><a href="compiler/$theindexhref">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>
|
|
"""
|
|
@else:
|
|
doc.body_toc_globallinks= """
|
|
<div id="global-links">
|
|
$body_toc_navlinks
|
|
$body_toc_indexlink
|
|
</div>
|
|
"""
|
|
@end
|
|
|
|
doc.body_toc = """
|
|
<div class="row">
|
|
<div class="three columns">
|
|
$body_toc_themeselect
|
|
$body_toc_globallinks
|
|
$body_toc_searchbox
|
|
$body_toc_groupsection
|
|
$tableofcontents
|
|
</div>
|
|
<div class="nine columns" id="content">
|
|
$seeSrc
|
|
<div id="tocRoot"></div>
|
|
$deprecationMsg
|
|
<p class="module-desc">$moduledesc</p>
|
|
$content
|
|
</div>
|
|
</div>
|
|
"""
|
|
|
|
doc.body_no_toc = """
|
|
$moduledesc
|
|
$content
|
|
"""
|
|
|
|
# $1 - number of listing in document, $2 - language (e.g. langNim), $3 - anchor
|
|
doc.listing_start = "<pre$3 class=\"listing\">"
|
|
doc.listing_end = "</pre>"
|
|
|
|
# * $analytics: Google analytics location, includes <script> tags
|
|
doc.file = """<?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>$title</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="${nimdoccss}?v=$nimVersion">
|
|
|
|
<!-- JS -->
|
|
<script type="text/javascript" src="${dochackjs}?v=$nimVersion"></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">$title</h1>$subtitle
|
|
$content
|
|
<div class="twelve-columns footer">
|
|
<span class="nim-sprite"></span>
|
|
<br>
|
|
<small style="color: var(--hint);">Made with Nim. Generated: $date $time UTC</small>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
$analytics
|
|
</body>
|
|
</html>
|
|
"""
|