Merge branch 'api-doc' into api-doc2

Conflicts:
	Makefile
	doc/cli/find.md
	lib/help.js
	man/man1/adduser.1
	man/man1/bin.1
	man/man1/build.1
	man/man1/bundle.1
	man/man1/cache.1
	man/man1/changelog.1
	man/man1/coding-style.1
	man/man1/completion.1
	man/man1/config.1
	man/man1/developers.1
	man/man1/docs.1
	man/man1/faq.1
	man/man1/find.1
	man/man1/folders.1
	man/man1/get.1
	man/man1/global.1
	man/man1/help-search.1
	man/man1/home.1
	man/man1/init.1
	man/man1/install.1
	man/man1/json.1
	man/man1/link.1
	man/man1/ln.1
	man/man1/npm.1
	man/man1/outdated.1
	man/man1/prefix.1
	man/man1/registry.1
	man/man1/removing-npm.1
	man/man1/rm.1
	man/man1/root.1
	man/man1/run-script.1
	man/man1/scripts.1
	man/man1/search.1
	man/man1/semver.1
	man/man1/set.1
	man/man1/tag.1
	man/man1/uninstall.1
	man/man1/update.1
	man/man1/version.1
	man/man1/whoami.1
	man/man3/author.3
	man/man3/deprecate.3
	man/man3/edit.3
	man/man3/explore.3
	man/man3/list.3
	man/man3/ls.3
	man/man3/owner.3
	man/man3/pack.3
	man/man3/prune.3
	man/man3/publish.3
	man/man3/rebuild.3
	man/man3/restart.3
	man/man3/start.3
	man/man3/stop.3
	man/man3/submodule.3
	man/man3/test.3
	man/man3/unpublish.3
	man/man3/view.3
	npm.js

.gitignore

@@ -8,6 +8,7 @@ test/root
 node_modules/ronn
 node_modules/.bin
 npm-debug.log
+html/api/*.html
 html/doc/*.html
-man1/*.1
-doc/index.md
+man/
+doc/*/index.md

Makefile

@@ -2,22 +2,30 @@ SHELL = bash
 
 markdowns = $(shell find doc -name '*.md' | grep -v 'index') README.md
 
-mandocs = $(shell find doc -name '*.md' \
-           |grep -v 'index.md' \
-           |sed 's|.md|.1|g' \
-           |sed 's|doc/|man1/|g' ) \
-           man1/README.1 \
-           man1/index.1
-
-htmldocs = $(shell find doc -name '*.md' \
-            |grep -v 'index.md' \
-            |sed 's|.md|.html|g' \
-            |sed 's|doc/|html/doc/|g' ) \
-            html/doc/README.html \
-            html/doc/index.html
-
-doc_subfolders = $(shell find doc -type d \
-                  |sed 's|doc/|man1/|g' )
+cli_mandocs = $(shell find doc/cli -name '*.md' \
+               |sed 's|.md|.1|g' \
+               |sed 's|doc/cli/|man/man1/|g' ) \
+               man/man1/README.1 \
+               man/man1/index.1
+
+api_mandocs = $(shell find doc/api -name '*.md' \
+               |sed 's|.md|.3|g' \
+               |sed 's|doc/api/|man/man3/|g' )
+
+cli_htmldocs = $(shell find doc/cli -name '*.md' \
+                |grep -v 'index.md' \
+                |sed 's|.md|.html|g' \
+                |sed 's|doc/cli/|html/doc/|g' ) \
+                html/doc/README.html \
+                html/doc/index.html
+
+api_htmldocs = $(shell find doc/api -name '*.md' \
+                |sed 's|.md|.html|g' \
+                |sed 's|doc/api/|html/api/|g' )
+
+mandocs = $(api_mandocs) $(cli_mandocs)
+
+htmldocs = $(api_htmldocs) $(cli_htmldocs)
 
 all: submodules doc
 
@@ -49,26 +57,50 @@ doc: node_modules/ronn $(mandocs) $(htmldocs)
 
 docclean: doc-clean
 doc-clean:
-	rm -rf node_modules/ronn doc/index.md $(mandocs) $(htmldocs) &>/dev/null || true
+	rm -rf \
+    node_modules/ronn \
+    doc/cli/index.md \
+    doc/api/index.md \
+    $(api_mandocs) \
+    $(cli_mandocs) \
+    $(api_htmldocs) \
+    $(cli_htmldocs) \
+		&>/dev/null || true
 
 node_modules/ronn:
 	node cli.js install git+https://github.com/isaacs/ronnjs.git
 
 # use `npm install ronn` for this to work.
-man1/README.1: README.md scripts/doc-build.sh package.json
+man/man1/README.1: README.md scripts/doc-build.sh package.json
+	scripts/doc-build.sh $< $@
+
+man/man1/%.1: doc/%.md scripts/doc-build.sh package.json
 	scripts/doc-build.sh $< $@
 
-man1/%.1: doc/%.md scripts/doc-build.sh package.json
+man/man3/%.3: doc/api/%.md man/man3 node_modules/ronn
 	scripts/doc-build.sh $< $@
 
 html/doc/README.html: README.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
 	scripts/doc-build.sh $< $@
 
-html/doc/%.html: doc/%.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
+html/doc/%.html: doc/cli/%.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
 	scripts/doc-build.sh $< $@
 
-doc/index.md: $(markdowns) scripts/index-build.js scripts/doc-build.sh package.json
-	node scripts/index-build.js > doc/index.md
+html/api/%.html: doc/api/%.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
+	scripts/doc-build.sh $< $@
+
+doc/cli/index.md: $(markdowns) scripts/index-build.js scripts/doc-build.sh package.json
+	node scripts/index-build.js > $@
+
+doc: man
+
+man: $(cli_docs) $(api_docs)
+
+man/man1:
+	[ -d man/man1 ] || mkdir -p man/man1
+
+man/man3:
+	[ -d man/man3 ] || mkdir -p man/man3
 
 test: submodules
 	node cli.js test
@@ -86,6 +118,7 @@ publish: link
 docpublish: doc-publish
 doc-publish: doc
 	rsync -vazu --stats --no-implied-dirs --delete html/doc/ npmjs.org:/var/www/npmjs.org/public/doc
+	rsync -vazu --stats --no-implied-dirs --delete html/api/ npmjs.org:/var/www/npmjs.org/public/api
 
 sandwich:
 	@[ $$(whoami) = "root" ] && (echo "ok"; echo "ham" > sandwich) || echo "make it yourself"

doc/api/bin.md

@@ -0,0 +1,15 @@
+npm-bin(3) -- Display npm bin folder
+====================================
+
+## SYNOPSIS
+
+    npm.commands.bin(args, callback)
+
+## DESCRIPTION
+
+Print the folder where npm will install executables.
+
+'args' is never used and callback is never called with data.
+'args' must be present or things will break.
+
+This function is not useful programmatically.

doc/api/commands.md

@@ -0,0 +1,70 @@
+npm-commands(3) -- npm commands
+===============================
+
+## SYNOPSIS
+
+    npm.commands.<command>(args, callback)
+
+## DESCRIPTION
+
+npm comes with a full set of commands, and each of the commands takes a
+similar set of arguments.
+
+In general, all commands on the command object take an **array** of positional
+argument **strings**. The last argument to any function is a callback. Some
+commands are special and take other optional arguments.
+
+All commands have their own man page. See `man npm-<command>` for command-line
+usage, or `man 3 npm-<command>` for programmatic usage.
+
+## COMMANDS
+
+### install
+
+Install a package.
+
+* "install"
+* "uninstall"
+  "cache"
+* "config"
+* "set"
+* "get"
+* "update"
+* "outdated"
+* "prune"
+* "submodule"
+* "pack"
+
+* "rebuild"
+* "link"
+
+* "publish"
+* "tag"
+  "adduser"
+* "unpublish"
+* "owner"
+* "deprecate"
+
+  "help"
+* "help-search"
+* "ls"
+* "search"
+* "view"
+* "init"
+* "version"
+* "edit"
+* "explore"
+* "docs"
+  "faq"
+* "root"
+* "prefix"
+* "bin"
+* "whoami"
+
+* "test"
+* "stop"
+* "start"
+* "restart"
+* "run-script"
+  "completion"
+

doc/api/config.md

@@ -0,0 +1,26 @@
+npm-config(3) -- Manage the npm configuration file
+==================================================
+
+## SYNOPSIS
+
+    npm.commands.config(args, callback)
+
+## DESCRIPTION
+
+This function acts much the same way as the command-line version.  The first
+element in the array tells config what to do. Possible values are:
+
+* 'set':
+  Sets a config parameter.  The second element in 'args' is interpreted as the
+  key, and the third element is interpreted as the value.
+* 'get':
+  Gets the value of a config parameter. The second element in 'args' is the
+  key to get the value of.
+* 'delete' ('rm' or 'del'):
+  Deletes a parameter from the config. The second element in 'args' is the
+  key to delete.
+* 'list' ('ls'):
+  Show all configs that aren't secret. No parameters necessary.
+* 'edit':
+  Opens the config file in the default editor. This command isn't very useful
+  programmatically, but it is made available.

doc/api/deprecate.md

@@ -0,0 +1,20 @@
+npm-deprecate(3) -- Deprecate a version of a package
+====================================================
+
+## SYNOPSIS
+
+    npm.commands.deprecate(args, callback)
+
+## DESCRIPTION
+
+This command will update the npm registry entry for a package, providing
+a deprecation warning to all who attempt to install it.
+
+The 'args' parameter must have exactly two elements:
+
+* package@version:
+  To specify a range, wrap the version in quotes (e.g. pkg@"< 1.2")
+* message
+
+Note that you must be the package owner to deprecate something.  See the
+`owner` and `adduser` help topics.

doc/api/docs.md

@@ -0,0 +1,19 @@
+npm-docs(3) -- Docs for a package in a web browser maybe
+========================================================
+
+## SYNOPSIS
+
+    npm.commands.docs(package, callback)
+
+## DESCRIPTION
+
+This command tries to guess at the likely location of a package's
+documentation URL, and then tries to open it using the `--browser`
+config param.
+
+Like other commands, the first parameter is an array. This command only
+uses the first element, which is expected to be a package name with an
+optional version number.
+
+This command will launch a browser, so this command may not be the most
+friendly for programmatic use.

doc/api/edit.md

@@ -0,0 +1,24 @@
+npm-edit(3) -- Edit an installed package
+========================================
+
+## SYNOPSIS
+
+    npm.commands.edit(package, callback)
+
+## DESCRIPTION
+
+Opens the package folder in the default editor (or whatever you've
+configured as the npm `editor` config -- see `npm help config`.)
+
+After it has been edited, the package is rebuilt so as to pick up any
+changes in compiled packages.
+
+For instance, you can do `npm install connect` to install connect
+into your package, and then `npm.commands.edit(["connect"], callback)`
+to make a few changes to your locally installed copy.
+
+The first parameter is a string array with a single element, the package
+to open. The package can optionally have a version number attached.
+
+Since this command opens an editor in a new process, be careful about where
+and how this is used.

doc/api/explore.md

@@ -0,0 +1,18 @@
+npm-explore(3) -- Browse an installed package
+=============================================
+
+## SYNOPSIS
+
+    npm.commands.explore(args, callback)
+
+## DESCRIPTION
+
+Spawn a subshell in the directory of the installed package specified.
+
+If a command is specified, then it is run in the subshell, which then
+immediately terminates.
+
+Note that the package is *not* automatically rebuilt afterwards, so be
+sure to use `npm rebuild <pkg>` if you make any changes.
+
+The first element in the 'args' parameter must be a package name.  After that is the optional command, which can be any number of strings. All of the strings will be combined into one, space-delimited command.

doc/api/find.md

@@ -0,0 +1 @@
+ls.md

doc/api/help-search.md

@@ -0,0 +1,30 @@
+npm-help-search(3) -- Search the help pages
+===========================================
+
+## SYNOPSIS
+
+    npm.commands.helpSearch(args, [silent,] callback)
+
+## DESCRIPTION
+
+This command is rarely useful, but it exists in the rare case that it is.
+
+This command takes an array of search terms and returns the help pages that
+match in order of best match.
+
+If there is only one match, then npm displays that help section. If there
+are multiple results, the results are printed to the screen formatted and the
+array of results is returned. Each result is an object with these properties:
+
+* hits:
+  A map of args to number of hits on that arg. For example, {"npm": 3}
+* found:
+  Total number of unique args that matched.
+* totalHits:
+  Total number of hits.
+* lines:
+  An array of all matching lines (and some adjacent lines).
+* file:
+  Name of the file that matched
+
+The silent parameter is not neccessary not used, but it may in the future.

doc/api/init.md

@@ -0,0 +1,29 @@
+npm init(3) -- Interactively create a package.json file
+=======================================================
+
+## SYNOPSIS
+
+    npm.commands.init(args, callback)
+
+## DESCRIPTION
+
+This will ask you a bunch of questions, and then write a package.json for you.
+
+It attempts to make reasonable guesses about what you want things to be set to,
+and then writes a package.json file with the options you've selected.
+
+If you already have a package.json file, it'll read that first, and default to
+the options in there.
+
+It is strictly additive, so it does not delete options from your package.json
+without a really good reason to do so.
+
+Since this function expects to be run on the command-line, it doesn't work very
+well as a programmatically. The best option is to roll your own, and since
+JavaScript makes it stupid simple to output formatted JSON, that is the
+preferred method. If you're sure you want to handle command-line prompting,
+then go ahead and use this programmatically.
+
+## SEE ALSO
+
+npm-json(1)