diff --git a/changelog.md b/changelog.md index 46428f9ab..6844d3791 100644 --- a/changelog.md +++ b/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 diff --git a/compiler/main.nim b/compiler/main.nim index 4a8fdf998..20a715886 100644 --- a/compiler/main.nim +++ b/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() diff --git a/doc/advopt.txt b/doc/advopt.txt index c8ff0845a..77531f5de 100644 --- a/doc/advopt.txt +++ b/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!) diff --git a/doc/docgen.rst b/doc/docgen.rst index 40c464ebd..e6693e153 100644 --- a/doc/docgen.rst +++ b/doc/docgen.rst @@ -84,51 +84,72 @@ Document Types HTML ---- -Generation of HTML documents is done via both the ``doc`` and ``doc2`` -commands. These command take either a single .nim file, outputting a single -.html file with the same base filename, or multiple .nim files, outputting -multiple .html files and, optionally, an index file. +Generation of HTML documents is done via the ``doc`` command. This command +takes either a single .nim file, outputting a single .html file with the same +base filename, or multiple .nim files, outputting multiple .html files and, +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 `_. -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 `_. -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 -implicitly by the compiler. This type of information is not available from -looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the -``doc`` command does. + +The older version of the ``doc`` command, now renamed ``doc0`` runs before +semantic checking which means it lacks some of the things ``doc`` will output. + +The ``doc0`` command:: + nim doc0 sample + +Partial Output:: + ... + proc helloWorld*(times: int) + ... + +Output can be viewed in full here: `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. -Note that this tool is built off of the ``doc`` command, and therefore is -performed before semantic checking. +takes in a .nim file, and outputs a .json file with the same base filename. Note +that this tool is built off of the ``doc`` command (previously ``doc2``), and +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 "hello world!"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 =============== diff --git a/tools/nim.bash-completion b/tools/nim.bash-completion index 4f62da986..1c199a0cf 100644 --- a/tools/nim.bash-completion +++ b/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 diff --git a/tools/nim.zsh-completion b/tools/nim.zsh-completion index 135649c90..57b5e163e 100644 --- a/tools/nim.zsh-completion +++ b/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