From c022120ebb8485b285990a6e8300c37a2f11afea Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Sun, 11 Jan 2026 21:39:01 +1100 Subject: [PATCH] Raw switch for `jsondoc` (#24568) Implements #21928 Adds a `--raw` (since thats what the original issue used, suggestions welcome) switch which stops the jsondoc gen from rendering rst/markdown. Implemented by making `genComment` check if it needs to return the raw string or not. This required switching the related procs to using `Option` to handle how `nil` values were returned before. The `nil` returns were eventually ignored so just ignoring `none(T)` has the same effect. Doesn't support `runnableExamples` since jsondocs doesn't support them either (cherry picked from commit c1e381ae8d02036fa8707e0434338b4cbe29bf21) --- changelog.md | 1 + compiler/commands.nim | 3 +++ compiler/docgen.nim | 13 ++++++++++--- compiler/options.nim | 4 ++++ doc/advopt.txt | 1 + tests/misc/mrawjson.nim | 5 +++++ tests/misc/trunner.nim | 12 ++++++++++++ 7 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 tests/misc/mrawjson.nim diff --git a/changelog.md b/changelog.md index 2ed76f8eb2..82986385de 100644 --- a/changelog.md +++ b/changelog.md @@ -112,6 +112,7 @@ errors. ## Tool changes +- Added `--raw` flag when generating JSON docs to not render markup. - Added `--stdinfile` flag to name of the file used when running program from stdin (defaults to `stdinfile.nim`) ## Documentation changes diff --git a/compiler/commands.nim b/compiler/commands.nim index 0dc83983e3..27d62fb3e7 100644 --- a/compiler/commands.nim +++ b/compiler/commands.nim @@ -1097,6 +1097,9 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo; of "shownonexports": expectNoArg(conf, switch, arg, pass, info) showNonExportedFields(conf) + of "raw": + expectNoArg(conf, switch, arg, pass, info) + docRawOutput(conf) of "exceptions": case arg.normalize of "cpp": conf.exc = excCpp diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 1ea8eafd5d..7be6b48208 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -433,6 +433,9 @@ proc getVarIdx(varnames: openArray[string], id: string): int = proc genComment(d: PDoc, n: PNode): PRstNode = if n.comment.len > 0: + if optDocRaw in d.conf.globalOptions: + return newRstLeaf(n.comment) + d.sharedState.currFileIdx = addRstFileIndex(d, n.info) try: result = parseRst(n.comment, @@ -1176,8 +1179,12 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): "col": %n.info.col} ) if comm != nil: - result.rst = comm - result.rstField = "description" + if optDocRaw in d.conf.globalOptions: + result.json["description"] = %comm.text + else: + result.rst = comm + result.rstField = "description" + if r.buf.len > 0: result.json["code"] = %r.buf if k in routineKinds: @@ -1418,7 +1425,7 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags of nkExportExceptStmt: discard "transformed into nkExportStmt by semExportExcept" of nkFromStmt, nkImportExceptStmt: traceDeps(d, n[0]) of nkCallKinds: - var comm: ItemPre = default(ItemPre) + var comm = default(ItemPre) getAllRunnableExamples(d, n, comm) if comm.len != 0: d.modDescPre.add(comm) else: discard diff --git a/compiler/options.nim b/compiler/options.nim index 3332393f6f..5dc1942157 100644 --- a/compiler/options.nim +++ b/compiler/options.nim @@ -110,6 +110,7 @@ type # please make sure we have under 32 options optEnableDeepCopy # ORC specific: enable 'deepcopy' for all types. optShowNonExportedFields # for documentation: show fields that are not exported optJsBigInt64 # use bigints for 64-bit integers in JS + optDocRaw # for documentation: Don't render markdown for JSON output optItaniumMangle # mangling follows the Itanium spec TGlobalOptions* = set[TGlobalOption] @@ -1039,6 +1040,9 @@ proc isDynlibOverride*(conf: ConfigRef; lib: string): bool = proc showNonExportedFields*(conf: ConfigRef) = incl(conf.globalOptions, optShowNonExportedFields) +proc docRawOutput*(conf: ConfigRef) = + incl(conf.globalOptions, optDocRaw) + proc expandDone*(conf: ConfigRef): bool = result = conf.ideCmd == ideExpand and conf.expandLevels == 0 and conf.expandProgress diff --git a/doc/advopt.txt b/doc/advopt.txt index 2d8300db87..b545a1ab4f 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -114,6 +114,7 @@ Advanced options: --docSeeSrcUrl:url activate 'see source' for doc command (see doc.item.seesrc in config/nimdoc.cfg) --docInternal also generate documentation for non-exported symbols + --raw turn off markup rendering for JSON docs --lineDir:on|off generation of #line directive on|off --embedsrc:on|off embeds the original source code as comments in the generated output diff --git a/tests/misc/mrawjson.nim b/tests/misc/mrawjson.nim new file mode 100644 index 0000000000..d824a43a83 --- /dev/null +++ b/tests/misc/mrawjson.nim @@ -0,0 +1,5 @@ +## Module description. See [someProc] +## another line + +proc someProc*(a, b: int) = + ## Code should be used like `someProc(1, 2)` diff --git a/tests/misc/trunner.nim b/tests/misc/trunner.nim index 6e5487d1b7..ac13bc5723 100644 --- a/tests/misc/trunner.nim +++ b/tests/misc/trunner.nim @@ -251,6 +251,18 @@ sub/mmain.idx""", context doAssert doSomething["col"].getInt == 0 doAssert doSomething["code"].getStr == "proc doSomething(x, y: int): int {.raises: [], tags: [], forbids: [].}" + block: # nim jsondoc --raw switch + let file = testsDir / "misc/mrawjson.nim" + let output = "nimcache_tjsondoc.json" + defer: removeFile(output) + let (msg, exitCode) = execCmdEx(fmt"{nim} jsondoc --raw -o:{output} {file}") + doAssert exitCode == 0, msg + + let data = parseFile(output) + doAssert data["moduleDescription"].getStr == "Module description. See [someProc]\nanother line" + let someProc = data["entries"][0] + doAssert someProc["description"].getStr == "Code should be used like `someProc(1, 2)`" + block: # further issues with `--backend` let file = testsDir / "misc/mbackend.nim" var cmd = fmt"{nim} doc -b:cpp --hints:off --nimcache:{nimcache} {file}"