js port of pdoc, with extentions
JavaScript
Pull request Compare This branch is 25 commits ahead, 288 commits behind nodeca:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
skins
tests
.DS_Store
.gitignore
.npmignore
.travis.yml
HISTORY.md
LICENSE
Makefile
README.md
package.json
syntax.md

README.md

Preface

ndoc is a totally awesome Javascript documentation tool written in Node.js, based on pdoc. This blog post identifies some of the advantages over other Javascript documentation ystems.

This fork of ndoc is extraordinarily modified (hacked? nah...). While you could run this through the command line, we don't, and prefer to exec ndoc as a backbone/submodule for a larger build process.

The changes here go beyond skins modified in the Jade templates. Core modifications include:

  • Creating a separate page for every class, including support for "[[ ]]"-notation linking
  • Adding "ellipsis" descriptions, truncating the full doc into 120 characters.
  • Linkifying everything (object types in arguments, return types, e.t.c.)
  • Allowing the same dirname for output to exist

Changes

One new caveat is that your source files must be two folders deep; for example, ./src/myDocs. This was made to support splitting objects into individual files, and given each of those objects a parent directory.

For example, you could have ./src/myDocs1/ and ./src/myDocs2/; all the objects in these files will output to ./out/myDocs1 and ./myDocs2, respectfully. Subfolders within the parent directory are flattened; e.g. files in ./src/myDocs1/foo still appear in ./out/myDocs1.

Furthermore, resources like CSS and Javascript in the ./skins now have their own folder called "resources," to differentiate them from the content.


Below is the original ndoc readme.

NDoc - JavaScript documentation generator

Build Status

NDoc is an inline comment parser and JavaScript documentation generator written in node.js. This project is inspired by PDoc. 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.
  • Added new tags: read-only, internal, chainable
  • Events support.

How to Install

We suppose that you already have node.js and npm installed. If not - try nvm. Then install NDoc globally

npm install -g ndoc

Usage

ndoc [options] <path>...

path PATH                   Source files location

Options:

  -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. It is similar to PDoc one, with some extentions (see start of this doc for details).

For developers

If you like to make patches or develop skins - install NDoc in developer mode:

git clone [your_fork_url]
cd ndoc
npm install --dev

After installation is done you can generate prototype documentation for test:

make test

Then open ./test/proto-doc/index.html. Here is hosted doc example. There are also some shortcuts in Makefile, if you make skin changes and need to constantly rebuild samples.

License

This project is distributed under MIT license.