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
86 lines
1.2 KiB
Markdown
86 lines
1.2 KiB
Markdown
.. title:: Welcome to Nim Book
|
|
.. importdoc:: page1
|
|
.. importdoc:: sections/1/intro
|
|
|
|
This is a test project for `nim book`:cmd:.
|
|
|
|
# Code
|
|
|
|
Inline code snippet:
|
|
|
|
```nim
|
|
proc twice*(a: int): int =
|
|
a * 2
|
|
```
|
|
|
|
This snippet is tested during documentation build:
|
|
|
|
```nim test
|
|
proc twice*(a: int): int =
|
|
a * 2
|
|
|
|
assert 10.twice == 20
|
|
```
|
|
|
|
The same but using `.. code::` directive:
|
|
|
|
.. code::
|
|
proc twice*(a: int): int =
|
|
a * 2
|
|
|
|
.. code::
|
|
:test:
|
|
|
|
proc twice*(a: int): int =
|
|
a * 2
|
|
|
|
assert 10.twice == 20
|
|
|
|
Code included from a source file:
|
|
|
|
.. include:: ./code1.nim
|
|
:code:
|
|
|
|
Selective inclusuion:
|
|
|
|
.. include:: ./code2.nim
|
|
:code:
|
|
:start-after:#doublestart
|
|
:end-before:#doubleend
|
|
|
|
Doesn't have to be Nim code:
|
|
|
|
.. include:: ./code3.py
|
|
:code: python
|
|
|
|
# Admonitions
|
|
|
|
.. note:: General info
|
|
|
|
.. warning::
|
|
It's dangerous to go alone!
|
|
|
|
Take this!
|
|
|
|
.. error:: Oh, snap :-(
|
|
|
|
.. important::
|
|
Admonitions can contain lists and code blocks.
|
|
|
|
- This
|
|
- is
|
|
- great!
|
|
|
|
.. code-block::
|
|
echo "Indeed"
|
|
|
|
# Links
|
|
|
|
This is a link to a heading on the same page: [Code].
|
|
|
|
This is a link to a heading on another page: [Heading].
|
|
|
|
Same, but with different syntax: `Heading`_.
|
|
|
|
You can use standard Markdown syntax, too: [I am a link](page1.html#heading)
|