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
54 lines
1.8 KiB
Nim
54 lines
1.8 KiB
Nim
# To run this, cd to the git repo root, and run "nim r nimdoc/booketester.nim".
|
|
# to change expected results (after carefully verifying everything), use -d:nimTestsNimdocFixup
|
|
|
|
import strutils, os
|
|
from std/private/gitutils import diffFiles
|
|
|
|
const fixup = defined(nimTestsNimdocFixup)
|
|
|
|
var
|
|
failures = 0
|
|
|
|
const
|
|
prjDir = "nimdoc" / "bookproject"
|
|
expDir = "expected"
|
|
outDir = "book"
|
|
|
|
proc exec(cmd: string) =
|
|
if execShellCmd(cmd) != 0:
|
|
quit("FAILURE: " & cmd)
|
|
|
|
proc testNimBook(fixup = false) =
|
|
putEnv("SOURCE_DATE_EPOCH", "100000")
|
|
const nimExe = getCurrentCompilerExe()
|
|
|
|
exec("$1 doc --index:on --project --outdir:$2 $3" % [nimExe,
|
|
prjDir / outDir / "api",
|
|
prjDir / "code1.nim"])
|
|
exec("$1 book --index:only --outdir:$2 $3" % [nimExe, prjDir / outDir, prjDir])
|
|
exec("$1 book --outdir:$2 $3" % [nimExe, prjDir / outDir, prjDir])
|
|
|
|
for expected in walkDirRec(prjDir / expDir, checkDir=true):
|
|
let versionCacheParam = "?v=" & $NimMajor & "." & $NimMinor & "." & $NimPatch
|
|
let produced = expected.replace('\\', '/').replace("/$1/" % [expDir], "/$1/" % [outDir])
|
|
if not fileExists(produced):
|
|
echo "FAILURE: files not found: ", produced
|
|
inc failures
|
|
let producedFile = readFile(produced).replace(versionCacheParam,"")
|
|
if readFile(expected) != producedFile:
|
|
echo "FAILURE: files differ: ", produced
|
|
echo diffFiles(expected, produced).output
|
|
inc failures
|
|
if fixup:
|
|
writeFile(expected, producedFile)
|
|
else:
|
|
echo "SUCCESS: files identical: ", produced
|
|
|
|
if failures == 0:
|
|
removeDir(prjDir / outDir)
|
|
|
|
testNimBook(fixup)
|
|
|
|
if failures > 0:
|
|
quit "$# failures occurred; see note in nimdoc/tester.nim regarding -d:nimTestsNimdocFixup" % $failures
|