Renamed jsondoc2 to jsondoc, similar to doc2 (#7279)

* Update information about jsondoc/jsondoc2

Manual was missing information about jsondoc2 which made it seem like
it didn't exist at all. This commit adds mention of the jsondoc2
command along with an example.

* Renamed jsondoc2 similar to doc2 and updated docs

doc2 was recently renamed to doc while doc was renamed to doc0. This
commits renames jsondoc to jsondoc2 and jsondoc2 to jsondoc0 to behave
tha same way. The documentation for doc/jsondoc was also lagging behind
this change which has also been fixed. I interpreted this as a soft
deprecation of doc and jsondoc and therefore removed them from the
auto-complete lists.

changelog.md

@@ -22,6 +22,9 @@
 
 ### Tool changes
 
+- ``jsondoc2`` has been renamed ``jsondoc``, similar to how ``doc2`` was renamed
+  ``doc``. The old ``jsondoc`` can still be invoked with ``jsondoc0``.
+
 ### Compiler changes
 
 ### Bugfixes

compiler/main.nim

@@ -210,14 +210,14 @@ proc mainCommand*(graph: ModuleGraph; cache: IdentCache) =
     gCmd = cmdRst2tex
     loadConfigs(DocTexConfig, cache)
     commandRst2TeX()
-  of "jsondoc":
+  of "jsondoc0":
     wantMainModule()
     gCmd = cmdDoc
     loadConfigs(DocConfig, cache)
     wantMainModule()
     defineSymbol("nimdoc")
     commandJson()
-  of "jsondoc2":
+  of "jsondoc2", "jsondoc":
     gCmd = cmdDoc
     loadConfigs(DocConfig, cache)
     wantMainModule()

doc/advopt.txt

@@ -7,7 +7,6 @@ Advanced commands:
   //rst2html                convert a reStructuredText file to HTML
   //rst2tex                 convert a reStructuredText file to TeX
   //jsondoc                 extract the documentation to a json file
-  //jsondoc2                extract the documentation to a json file (uses doc2)
   //ctags                   create a tags file
   //buildIndex              build an index for the whole documentation
   //run                     run the project (with Tiny C backend; buggy!)

doc/docgen.rst

@@ -84,51 +84,72 @@ Document Types
 HTML
 ----
 
-Generation of HTML documents is done via both the ``doc`` and ``doc2``
+Generation of HTML documents is done via the ``doc`` command. This command
-commands. These command take either a single .nim file, outputting a single
+takes either a single .nim file, outputting a single .html file with the same
-.html file with the same base filename, or multiple .nim files, outputting
+base filename, or multiple .nim files, outputting multiple .html files and,
-multiple .html files and, optionally, an index file.
+optionally, an index file.
 
 The ``doc`` command::
   nim doc sample
 
-Partial Output::
-  ...
-  proc helloWorld*(times: int)
-  ...
-
-Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
-The next command, called ``doc2``, is very similar to the ``doc`` command, but
-will be run after the compiler performs semantic checking on the input nim
-module(s), which allows it to process macros.
-
-The ``doc2`` command::
-  nim doc2 sample
-
 Partial Output::
   ...
   proc helloWorld(times: int) {.raises: [], tags: [].}
   ...
 
 The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_.
-As you can see, the tool has extracted additional information provided to it by
+
-the compiler beyond what the ``doc`` command provides, such as pragmas attached
+The older version of the ``doc`` command, now renamed ``doc0`` runs before
-implicitly by the compiler. This type of information is not available from
+semantic checking which means it lacks some of the things ``doc`` will output.
-looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the
+
-``doc`` command does.
+The ``doc0`` command::
+  nim doc0 sample
+
+Partial Output::
+  ...
+  proc helloWorld*(times: int)
+  ...
+
+Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
+As you can see, the tool has extracted less information than what the ``doc``
+command provides, such as pragmas attached implicitly by the compiler. This type
+of information is not available from looking at the AST (Abstract Syntax Tree)
+prior to semantic checking, which is why ``doc0`` doesn't show it.
 
 
 JSON
 ----
 
 Generation of JSON documents is done via the ``jsondoc`` command. This command
-takes in a .nim file, and outputs a .json file with the same base filename.
+takes in a .nim file, and outputs a .json file with the same base filename. Note
-Note that this tool is built off of the ``doc`` command, and therefore is
+that this tool is built off of the ``doc`` command (previously ``doc2``), and
-performed before semantic checking.
+contains the same information.
 
 The ``jsondoc`` command::
   nim jsondoc sample
 
+Output::
+  {
+    "orig": "docgen_sample.nim",
+    "nimble": "",
+    "entries": [
+      {
+        "name": "helloWorld",
+        "type": "skProc",
+        "line": 5,
+        "col": 0,
+        "description": "Takes an integer and outputs as many &quot;hello world!&quot;s",
+        "code": "proc helloWorld(times: int) {.raises: [], tags: [].}"
+      }
+    ]
+  }
+
+Similarly to the old ``doc`` command the old ``jsondoc`` command has been
+renamed ``jsondoc0``.
+ 
+The ``jsondoc0`` command::
+  nim jsondoc0 sample
+
 Output::
   [
     {
@@ -142,6 +163,8 @@ Output::
     }
   ]
 
+Note that the ``jsondoc`` command outputs it's JSON without pretty-printing it,
+while ``jsondoc0`` outputs pretty-printed JSON.
 
 Related Options
 ===============

tools/nim.bash-completion

@@ -10,7 +10,7 @@ _nim()
 
  if [ $COMP_CWORD -eq 1 ] ; then
    # first item - suggest commands
-   kw="compile c doc doc2 compileToC cc compileToCpp cpp compileToOC objc js e rst2html rst2tex jsondoc jsondoc2 buildIndex genDepend dump check"
+   kw="compile c doc compileToC cc compileToCpp cpp compileToOC objc js e rst2html rst2tex jsondoc buildIndex genDepend dump check"
    COMPREPLY=( $( compgen -W "${kw}" -- $cur ) )
    return 0
  fi

tools/nim.zsh-completion

@@ -5,7 +5,6 @@ _nim() {
     ':command:((
       {compile,c}\:compile\ project\ with\ default\ code\ generator\ C
       doc\:generate\ the\ documentation\ for\ inputfile
-      doc2\:generate\ the\ documentation\ for\ inputfile
       {compileToC,cc}\:compile\ project\ with\ C\ code\ generator
       {compileToCpp,cpp}\:compile\ project\ to\ C++\ code
       {compileToOC,objc}\:compile\ project\ to\ Objective\ C\ code
@@ -14,7 +13,6 @@ _nim() {
       rst2html\:convert\ a\ reStructuredText\ file\ to\ HTML
       rst2tex\:convert\ a\ reStructuredText\ file\ to\ TeX
       jsondoc\:extract\ the\ documentation\ to\ a\ json\ file
-      jsondoc2\:extract\ documentation\ to\ a\ json\ file\ using\ doc2
       buildIndex\:build\ an\ index\ for\ the\ whole\ documentation
       genDepend\:generate\ a\ DOT\ file\ containing\ the\ module\ dependency\ graph
       dump\:dump\ all\ defined\ conditionals\ and\ search\ paths