ndoc - npm Package Compare versions

Comparing version 1.0.7 to 2.0.0

HISTORY.md

@@ -0,1 +1,17 @@
+2.0.0 / 2012-07-02
+------------------
+
+* `Internal` methods are now skipped by default.
+* Stop on collisions, instead of warning
+* Bundled mode (all doc in single file), layout/styles cleanup.
+* Highlight on build time (no more hangs on big docs load)
+* Ability to add github ribbon.
+* Multiple folders/files support.
+* Parcers/Generators can be attached as external modules
+* Reorganized options (see new help).
+* Options can be loaded from file now.
+* Grand refactoring.
+* Multiple bugfixes (see ussue tracker).
+
+
 1.0.7 / 2012-02-09
@@ -7,2 +23,3 @@ ------------------
 
+
 1.0.6 / 2012-02-05
@@ -14,2 +31,3 @@ ------------------
 
+
 1.0.5 / 2012-01-04
@@ -16,0 +34,0 @@ ------------------

package.json

 {
   "name"            : "ndoc",
-  "version"         : "1.0.7",
+  "version"         : "2.0.0",
   "description"     : "JavaScript API documentor with simple syntax.",
   "keywords"        : [
-                        "api", "doc", "apidoc", "jsdoc", "autodoc",
-                        "documentation", "documentor", "pdoc", "prototype"
+                        "api", "doc", "apidoc", "documentation", "pdoc"
                       ],
@@ -21,20 +20,25 @@ "homepage"        : "https://github.com/nodeca/ndoc",
 
-  "bin"             : { "ndoc": "bin/ndoc" },
+  "bin"             : { "ndoc": "bin/ndoc.js" },
   "main"            : "./lib/index.js",
 
   "dependencies"    : {
-                        "nomnom"    : "1.5.1",
-                        "jade"      : "0.18.0",
-                        "marked"    : "0.1.9",
-                        "fs-tools"  : "0.2.1"
+                        "async"       : "~0.1.22",
+                        "argparse"    : "~0.1.3",
+                        "minimatch"   : "~0.2.5",
+                        "mincer"      : "~0.2.2",
+                        "uglify-js"   : "~1.3.2",
+                        "csso"        : "~1.2.14",
+                        "jade"        : "~0.26.0",
+                        "stylus"      : "~0.27.0",
+                        "nib"         : "~0.5.0",
+                        "marked"      : "~0.2.0",
+                        "underscore"  : "~1.3.0",
+                        "fs-tools"    : "~0.2.2",
+                        "highlight.js": "~7.0.1",
+                        "less"        : "~1.3.0"
                       },
-  "devDependencies" : {
-                        "jison"     : "0.2.12",
-                        "stylus"    : "0.19.3",
-                        "jslint"  : "https://github.com/reid/node-jslint/tarball/6131ebf5713274871b89735105e3286131804771"
-                      },
+  "devDependencies" : { "jison": "~0.3.0" },
+  "engines"         : { "node": ">= 0.6.0" },
 
-  "engines"         : { "node": "> 0.4.11" },
-
   "preferGlobal"    : true
 }

README.md

 # NDoc - JavaScript documentation generator
 [![Build Status](https://secure.travis-ci.org/nodeca/ndoc.png)](http://travis-ci.org/nodeca/ndoc)
 
-NDoc is an inline comment parser and JavaScript documentation generator written in node.js.
-This project is inspired by [PDoc](http://pdoc.org/syntax.html). It tries to keep compatibility,
-but has some differences:
+NDoc is an inline comment parser and JavaScript documentation generator written
+in Node.JS. This project was inspired by [PDoc](http://pdoc.org/syntax.html).
+It tries to keep compatibility, but has some differences:
 
-- NDoc is a CLI tool, not library. It doesn't require additional programming to execute.
-- Clarified EBNF syntax. Definitions now **MUST** be separated with an empty line from the following comments.
-- Added options for `deprecated` tag: you can set versions, when tag was deprecated and
-  when it will be removed.
+- NDoc is primarily a CLI tool, so you don't need to code your documentor,
+  although it can be easily used as [library](#using-ndoc-as-module).
+- Clarified EBNF syntax. Definitions now **MUST** be separated with an empty
+  line from the following comments.
+- Added options for `deprecated` tag: you can set versions, when tag was
+  deprecated and when method/property will be removed.
 - Added new tags: `read-only`, `internal`, `chainable`
@@ -18,4 +20,4 @@ - Events support.
 
-We suppose that you already have `node.js` and `npm` installed.
-If not - try [nvm](https://github.com/creationix/nvm). Then install NDoc globally
+We suppose that you already have `Node` and `npm` installed.
+If not - try [nvm](https://github.com/creationix/nvm).
 
@@ -27,35 +29,49 @@ npm install -g ndoc
 
-    ndoc [options] <path>...
+    usage: ndoc [-h] [-v] [--exclude PATTERN] [-o PATH] [--use PLUGIN]
+                [-r RENDERER] [--link-format FORMAT] [-t TEMPLATE] [--show-all]
+                [--package PACKAGE] [--index FILE] [--gh-ribbon URL]
+                [--broken-links ACTION] [--noenv]
+                PATH[PATH ...]
 
-    path PATH                   Source files location
+    Positional arguments:
+      PATH                            Source files location
 
-    Options:
+    Optional arguments:
+      -h, --help                      Show this help message and exit.
+      -v, --version                   Show program's version number and exit.
+      --exclude PATTERN               Glob patterns of filenames to exclude (you 
+                                      can use wildcards: ?, *, **).
+      -o PATH, --output PATH          Resulting file(s) location.
+      --use PLUGIN                    Load custom plugin.
+      -r RENDERER, --render RENDERER  Documentation renderer (html, json). More 
+                                      can be added by custom plugins.
+      --link-format FORMAT            View sources link (no links by default) 
+                                      format. You can use `{file}` and `{line}` 
+                                      and any of `{package.*}` variables for 
+                                      interpolation.
+      -t TEMPLATE, --title TEMPLATE   Documentation title template. You can use 
+                                      any of `{package.*}` variables for 
+                                      interpolation. DEFAULT: `{package.name} 
+                                      {package.version} API documentation`
+      --show-all                      By default `internal` methods/properties 
+                                      are not shown. This trigger makes ndoc show 
+                                      all methods/properties
+      --package PACKAGE               Read specified package.json FILE. When not 
+                                      specified, read ./package.json if such file 
+                                      exists.
+      --index FILE                    Index file (with introduction text), e.g. 
+                                      README.md file.
+      --gh-ribbon URL                 Add "Fork me on GitHub" ribbon with given 
+                                      URL. You can use any of `{package.*}` 
+                                      variables for interpolation.
+      --broken-links ACTION           What to do if broken link occurred (show, 
+                                      hide, throw). DEFAULT: `show`.
+      --noenv                         Ignore .ndocrc
 
-      -h, --help                Output usage information
-      -o, --output PATH         Resulting file(s) location [doc]
-      -e, --extension STRING    Source files extension [js]
-      -f, --format <html|js>    Documentation format [html]
-      -i, --index PATH          Index file [README.md]
-      -t, --title TITLE         Documentation title
-                                Supports interpolation. See notes for --link-format.
-      -l, --link-format         FMT String format for link to source file [{file}#L{line}]
-                                {url} is substituted with the URL of repository read from manifest file
-                                {file} is substituted with the name of the source file
-                                {line} is substituted with the line number within the source file
-                                E.g. http://github.com/nodeca/ndoc/{file}#L{line}
-                                {package.XXX} is substituted with XXX key of package.json, if any
-      --view-source-label TXT   Text for "View source" link
-      --skin PATH               Custom templates
-      -b, --broken-links ACTION What to do if broken link occured. Can be one of 'show', 'hide', 'throw'.
-                                Default is 'hide'
 
-NDoc uses data from `package.json` in current folder, if found one. This helps to minimize number of options when building documentation for node.js projects. For example, you can just run:
-
-    ndoc ./lib
-
-
 ## Syntax
 
 [NDoc Syntax](https://github.com/nodeca/ndoc/blob/master/syntax.md).
-It is similar to [PDoc](https://github.com/tobie/pdoc) one, with some extentions (see start of this doc for details).
+It is similar to [PDoc](https://github.com/tobie/pdoc) one, with some
+extentions (see start of this doc for details).
 
@@ -65,18 +81,53 @@
 
-If you like to make patches or develop skins - install NDoc in developer mode:
+You can generate prototype documentation for test:
 
-    git clone [your_fork_url]
-    cd ndoc
-    npm install --dev
+    make test
 
-After installation is done you can generate prototype documentation for test:
+Then open `./tests/prototype-doc/index.html`.
+Here is [hosted example](http://nodeca.github.com/ndoc/tests/prototype/).
 
-    make test
 
-Then open `./test/proto-doc/index.html`. Here is [hosted doc example](http://nodeca.github.com/ndoc/tests/doc/). There are also some shortcuts in [Makefile](https://github.com/nodeca/ndoc/blob/master/Makefile),
-if you make skin changes and need to constantly rebuild samples.
+#### Custom parsers and renderers
 
+You can create and use your own parser/renderer via `--use` option. Get one of
+the [parsers][parsers] or [renderers][renderers] as a base template, copy it
+into separate folder. Create package.json and modify it to fit your needs. Then
+attach it with `--use my-module` argument.
 
+[parsers]: https://github.com/nodeca/ndoc/blob/master/lib/ndoc/plugins/parsers
+[renderers]: https://github.com/nodeca/ndoc/blob/master/lib/ndoc/plugins/renderers
+
+
+#### Using NDoc as module
+
+You can use NDoc as module, for example, to override default options processing.
+
+``` javascript
+var NDoc = require('ndoc');
+
+
+var options = {
+  linkFormat  : 'http://example.com/{file}#{line}',
+  output:     : 'doc'
+};
+
+
+NDoc.parse(['lib/my-module.js'], options, function (err, ast) {
+  if (err) {
+    console.error(err);
+    process.exit(1);
+  }
+
+  NDoc.render('html', ast, options, function (err) {
+    if (err) {
+      console.error(err);
+      process.exit(1);
+    }
+  });
+});
+```
+
+
 ## License
 
 This project is distributed under [MIT](https://github.com/nodeca/ndoc/blob/master/LICENSE) license.

New alerts

Non-existent author

Supply chain risk

The package was published by an npm account that no longer exists.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

426035

60.4%

Dev dependency count

1

-66.67%

Number of package files

67

39.58%

Lines of code

10005

254.41%

Number of lines in readme file

131

63.75%

Worsened metrics

Dependency count

14

250%

Number of high supply chain risk alerts

1

Infinity%

Number of low supply chain risk alerts

24

300%

Dependency changes

• + Added

  argparse@~0.1.3

• + Added

  async@~0.1.22

• + Added

  csso@~1.2.14

• + Added

  highlight.js@~7.0.1

• + Added

  less@~1.3.0

• + Added

  mincer@~0.2.2

• + Added

  minimatch@~0.2.5

• + Added

  nib@~0.5.0

• + Added

  stylus@~0.27.0

• + Added

  uglify-js@~1.3.2

• + Added

  underscore@~1.3.0

• + Added

  argparse@0.1.16
  (transitive)

• + Added

  async@0.1.220.2.10
  (transitive)

• + Added

  commander@0.6.1
  (transitive)

• + Added

  csso@1.2.18
  (transitive)

• + Added

  cssom@0.2.5
  (transitive)

• + Added

  debug@4.4.1
  (transitive)

• + Added

  fs-tools@0.2.11
  (transitive)

• + Added

  highlight.js@7.0.1
  (transitive)

• + Added

  hike@0.1.4
  (transitive)

• + Added

  jade@0.26.3
  (transitive)

• + Added

  less@1.3.3
  (transitive)

• + Added

  lodash@2.4.2
  (transitive)

• + Added

  lru-cache@2.7.3
  (transitive)

• + Added

  marked@0.2.10
  (transitive)

• + Added

  mimoza@0.1.1
  (transitive)

• + Added

  mincer@0.2.7
  (transitive)

• + Added

  minimatch@0.2.14
  (transitive)

• + Added

  mkdirp@0.3.0
  (transitive)

• + Added

  ms@2.1.3
  (transitive)

• + Added

  nib@0.5.0
  (transitive)

• + Added

  shellwords@0.1.1
  (transitive)

• + Added

  sigmund@1.0.1
  (transitive)

• + Added

  stylus@0.27.2
  (transitive)

• + Added

  types@0.1.1
  (transitive)

• + Added

  uglify-js@1.3.5
  (transitive)

• + Added

  underscore@1.3.31.7.0
  (transitive)

• + Added

  underscore.string@2.4.0
  (transitive)

• + Added

  ycssmin@1.0.1
  (transitive)

• - Removed

  nomnom@1.5.1

• - Removed

  async@0.1.15
  (transitive)

• - Removed

  colors@0.5.1
  (transitive)

• - Removed

  commander@0.2.1
  (transitive)

• - Removed

  fs-tools@0.2.1
  (transitive)

• - Removed

  jade@0.18.0
  (transitive)

• - Removed

  marked@0.1.9
  (transitive)

• - Removed

  mkdirp@3.0.1
  (transitive)

• - Removed

  nomnom@1.5.1
  (transitive)

• - Removed

  underscore@1.1.71.3.1
  (transitive)

• Updated

  fs-tools@~0.2.2

• Updated

  jade@~0.26.0

• Updated

  marked@~0.2.0