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
1.2 KiB
.. title:: Welcome to Nim Book .. importdoc:: page1 .. importdoc:: sections/1/intro
This is a test project for nim book:cmd:.
Code
Inline code snippet:
proc twice*(a: int): int =
a * 2
This snippet is tested during documentation build:
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