Raw switch for jsondoc

changelog.md

@@ -69,4 +69,4 @@ errors.
 
 ## Tool changes
 
-
+- Added `--raw` flag when generating JSON docs to not render markup.

compiler/commands.nim

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

@@ -24,6 +24,7 @@ import
 import packages/docutils/rstast except FileIndex, TLineInfo
 
 import std/[os, strutils, strtabs, algorithm, json, osproc, tables, intsets, xmltree, sequtils]
+import std/options as optionals
 from std/uri import encodeUrl
 from nodejs import findNodeJs
 
@@ -112,6 +113,9 @@ type
 
 proc add(dest: var ItemPre, rst: PRstNode) = dest.add ItemFragment(isRst: true, rst: rst)
 proc add(dest: var ItemPre, str: string) = dest.add ItemFragment(isRst: false, str: str)
+proc add(dest: var ItemPre, item: sink Option[ItemFragment]) =
+  if item.isSome():
+    dest.add item.unsafeGet
 
 proc addRstFileIndex(d: PDoc, fileIndex: lineinfos.FileIndex): rstast.FileIndex =
   let invalid = rstast.FileIndex(-1)
@@ -431,36 +435,45 @@ proc getVarIdx(varnames: openArray[string], id: string): int =
       return i
   result = -1
 
-proc genComment(d: PDoc, n: PNode): PRstNode =
+func initItemFragment(rst: PRstNode): ItemFragment =
+  ItemFragment(isRst: true, rst: rst)
+
+func initItemFragment(str: string): ItemFragment =
+  ItemFragment(isRst: false, str: str)
+
+proc genComment(d: PDoc, n: PNode): Option[ItemFragment] =
   if n.comment.len > 0:
+    if optDocRaw in d.conf.globalOptions:
+      return some initItemFragment(n.comment)
+
     d.sharedState.currFileIdx = addRstFileIndex(d, n.info)
     try:
-      result = parseRst(n.comment,
+      result = some initItemFragment(parseRst(n.comment,
                         toLinenumber(n.info),
                         toColumn(n.info) + DocColOffset,
-                        d.conf, d.sharedState)
+                        d.conf, d.sharedState))
     except ERecoverableError:
-      result = newRstNode(rnLiteralBlock, @[newRstLeaf(n.comment)])
+      result = some initItemFragment(newRstNode(rnLiteralBlock, @[newRstLeaf(n.comment)]))
   else:
-    result = nil
+    result = none(ItemFragment)
 
-proc genRecCommentAux(d: PDoc, n: PNode): PRstNode =
-  if n == nil: return nil
+proc genRecCommentAux(d: PDoc, n: PNode): Option[ItemFragment] =
+  if n == nil: return none(ItemFragment)
   result = genComment(d, n)
-  if result == nil:
+  if result.isNone:
     if n.kind in {nkStmtList, nkStmtListExpr, nkTypeDef, nkConstDef, nkTypeClassTy,
                   nkObjectTy, nkRefTy, nkPtrTy, nkAsgn, nkFastAsgn, nkSinkAsgn, nkHiddenStdConv}:
       # notin {nkEmpty..nkNilLit, nkEnumTy, nkTupleTy}:
       for i in 0..<n.len:
         result = genRecCommentAux(d, n[i])
-        if result != nil: return
+        if result.isSome: return
   else:
     n.comment = ""
 
-proc genRecComment(d: PDoc, n: PNode): PRstNode =
-  if n == nil: return nil
+proc genRecComment(d: PDoc, n: PNode): Option[ItemFragment] =
+  if n == nil: return none(ItemFragment)
   result = genComment(d, n)
-  if result == nil:
+  if result.isNone:
     if n.kind in {nkProcDef, nkFuncDef, nkMethodDef, nkIteratorDef,
                   nkMacroDef, nkTemplateDef, nkConverterDef}:
       result = genRecCommentAux(d, n[bodyPos])
@@ -1175,9 +1188,13 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false):
   result = JsonItem(json: %{ "name": %name, "type": %($k), "line": %n.info.line.int,
                    "col": %n.info.col}
   )
-  if comm != nil:
-    result.rst = comm
-    result.rstField = "description"
+  if comm.isSome:
+    let c = comm.unsafeGet
+    if c.isRst:
+      result.rst = c.rst
+      result.rstField = "description"
+    else:
+      result.json["description"] = %c.str
   if r.buf.len > 0:
     result.json["code"] = %r.buf
   if k in routineKinds:
@@ -1375,7 +1392,8 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags
     d.modDeprecationMsg.add(genDeprecationMsg(d, pragmaNode))
     let doctypeNode = findPragma(n, wDoctype)
     setDoctype(d, doctypeNode)
-  of nkCommentStmt: d.modDescPre.add(genComment(d, n))
+  of nkCommentStmt:
+    d.modDescPre.add(genComment(d, n))
   of nkProcDef, nkFuncDef:
     when useEffectSystem: documentRaises(d.cache, n)
     genItemAux(skProc)
@@ -1415,7 +1433,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
@@ -1570,7 +1588,7 @@ proc generateJson*(d: PDoc, n: PNode, config: ConfigRef, includeComments: bool =
     setDoctype(d, doctypeNode)
   of nkCommentStmt:
     if includeComments:
-      d.add JsonItem(rst: genComment(d, n), rstField: "comment",
+      d.add JsonItem(rst: genComment(d, n).get().rst, rstField: "comment",
                      json: %Table[string, string]())
     else:
       d.modDescPre.add(genComment(d, n))

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
 
   TGlobalOptions* = set[TGlobalOption]
 
@@ -1036,6 +1037,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

@@ -113,6 +113,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}"