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

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

compiler/commands.nim

@@ -1109,6 +1109,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

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

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
     optCompress               # turn on AST compression by converting it to NIF
     optWithinConfigSystem     # we still compile within the configuration system
@@ -1046,6 +1047,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
 

doc/advopt.txt

@@ -115,6 +115,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

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)`

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}"