diff options
author | isaacs <i@izs.me> | 2011-09-25 07:58:50 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2011-09-25 07:58:50 +0400 |
commit | 308dd4254715f7845a1d2f84b05bc51cfb018890 (patch) | |
tree | b078d210051b6eacbeff16cb56d2fd060400a090 | |
parent | a726b94c66d918a276c1acd8112ce4659809d152 (diff) | |
parent | 12e22fb2709f73fa9300ea81e3ac5b5620870492 (diff) |
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
-rw-r--r-- | .gitignore | 5 | ||||
-rw-r--r-- | Makefile | 77 | ||||
l--------- | doc/api/author.md (renamed from doc/author.md) | 0 | ||||
-rw-r--r-- | doc/api/bin.md | 15 | ||||
-rw-r--r-- | doc/api/commands.md | 70 | ||||
-rw-r--r-- | doc/api/config.md | 26 | ||||
-rw-r--r-- | doc/api/deprecate.md | 20 | ||||
-rw-r--r-- | doc/api/docs.md | 19 | ||||
-rw-r--r-- | doc/api/edit.md | 24 | ||||
-rw-r--r-- | doc/api/explore.md | 18 | ||||
l--------- | doc/api/find.md | 1 | ||||
l--------- | doc/api/get.md (renamed from doc/get.md) | 0 | ||||
-rw-r--r-- | doc/api/help-search.md | 30 | ||||
l--------- | doc/api/home.md (renamed from doc/home.md) | 0 | ||||
-rw-r--r-- | doc/api/init.md | 29 | ||||
-rw-r--r-- | doc/api/install.md | 19 | ||||
-rw-r--r-- | doc/api/link.md | 33 | ||||
l--------- | doc/api/list.md | 1 | ||||
l--------- | doc/api/ln.md | 1 | ||||
-rw-r--r-- | doc/api/load.md | 26 | ||||
-rw-r--r-- | doc/api/ls.md | 50 | ||||
-rw-r--r-- | doc/api/npm.md | 30 | ||||
-rw-r--r-- | doc/api/outdated.md | 13 | ||||
-rw-r--r-- | doc/api/owner.md | 31 | ||||
-rw-r--r-- | doc/api/pack.md | 19 | ||||
-rw-r--r-- | doc/api/prefix.md | 15 | ||||
-rw-r--r-- | doc/api/prune.md | 17 | ||||
-rw-r--r-- | doc/api/publish.md | 30 | ||||
-rw-r--r-- | doc/api/rebuild.md | 16 | ||||
-rw-r--r-- | doc/api/restart.md | 22 | ||||
l--------- | doc/api/rm.md | 1 | ||||
-rw-r--r-- | doc/api/root.md | 15 | ||||
-rw-r--r-- | doc/api/run-script.md | 27 | ||||
-rw-r--r-- | doc/api/search.md | 35 | ||||
l--------- | doc/api/set.md (renamed from doc/set.md) | 0 | ||||
-rw-r--r-- | doc/api/start.md | 13 | ||||
-rw-r--r-- | doc/api/stop.md | 13 | ||||
-rw-r--r-- | doc/api/submodule.md | 28 | ||||
-rw-r--r-- | doc/api/tag.md | 23 | ||||
-rw-r--r-- | doc/api/test.md | 16 | ||||
-rw-r--r-- | doc/api/uninstall.md | 16 | ||||
-rw-r--r-- | doc/api/unpublish.md | 20 | ||||
-rw-r--r-- | doc/api/update.md | 11 | ||||
-rw-r--r-- | doc/api/version.md | 18 | ||||
-rw-r--r-- | doc/api/view.md | 82 | ||||
-rw-r--r-- | doc/api/whoami.md | 15 | ||||
-rw-r--r-- | doc/cli/adduser.md (renamed from doc/adduser.md) | 0 | ||||
l--------- | doc/cli/author.md | 1 | ||||
-rw-r--r-- | doc/cli/bin.md (renamed from doc/bin.md) | 0 | ||||
-rw-r--r-- | doc/cli/build.md (renamed from doc/build.md) | 0 | ||||
-rw-r--r-- | doc/cli/bundle.md (renamed from doc/bundle.md) | 0 | ||||
-rw-r--r-- | doc/cli/cache.md (renamed from doc/cache.md) | 0 | ||||
-rw-r--r-- | doc/cli/changelog.md (renamed from doc/changelog.md) | 0 | ||||
-rw-r--r-- | doc/cli/coding-style.md (renamed from doc/coding-style.md) | 0 | ||||
-rw-r--r-- | doc/cli/completion.md (renamed from doc/completion.md) | 0 | ||||
-rw-r--r-- | doc/cli/config.md (renamed from doc/config.md) | 0 | ||||
-rw-r--r-- | doc/cli/deprecate.md (renamed from doc/deprecate.md) | 0 | ||||
-rw-r--r-- | doc/cli/developers.md (renamed from doc/developers.md) | 0 | ||||
-rw-r--r-- | doc/cli/docs.md (renamed from doc/docs.md) | 0 | ||||
-rw-r--r-- | doc/cli/edit.md (renamed from doc/edit.md) | 0 | ||||
-rw-r--r-- | doc/cli/explore.md (renamed from doc/explore.md) | 0 | ||||
-rw-r--r-- | doc/cli/faq.md (renamed from doc/faq.md) | 0 | ||||
l--------- | doc/cli/find.md | 1 | ||||
-rw-r--r-- | doc/cli/folders.md (renamed from doc/folders.md) | 0 | ||||
l--------- | doc/cli/get.md | 1 | ||||
l--------- | doc/cli/global.md (renamed from doc/global.md) | 0 | ||||
-rw-r--r-- | doc/cli/help-search.md (renamed from doc/help-search.md) | 0 | ||||
l--------- | doc/cli/home.md | 1 | ||||
-rw-r--r-- | doc/cli/init.md (renamed from doc/init.md) | 0 | ||||
-rw-r--r-- | doc/cli/install.md (renamed from doc/install.md) | 0 | ||||
-rw-r--r-- | doc/cli/json.md (renamed from doc/json.md) | 0 | ||||
-rw-r--r-- | doc/cli/link.md (renamed from doc/link.md) | 0 | ||||
-rw-r--r-- | doc/cli/list.md (renamed from doc/list.md) | 0 | ||||
l--------- | doc/cli/ln.md (renamed from doc/ln.md) | 0 | ||||
l--------- | doc/cli/ls.md (renamed from doc/ls.md) | 0 | ||||
-rw-r--r-- | doc/cli/npm.md (renamed from doc/npm.md) | 0 | ||||
-rw-r--r-- | doc/cli/outdated.md (renamed from doc/outdated.md) | 0 | ||||
-rw-r--r-- | doc/cli/owner.md (renamed from doc/owner.md) | 0 | ||||
-rw-r--r-- | doc/cli/pack.md (renamed from doc/pack.md) | 0 | ||||
-rw-r--r-- | doc/cli/prefix.md (renamed from doc/prefix.md) | 0 | ||||
-rw-r--r-- | doc/cli/prune.md (renamed from doc/prune.md) | 0 | ||||
-rw-r--r-- | doc/cli/publish.md (renamed from doc/publish.md) | 0 | ||||
-rw-r--r-- | doc/cli/rebuild.md (renamed from doc/rebuild.md) | 0 | ||||
-rw-r--r-- | doc/cli/registry.md (renamed from doc/registry.md) | 0 | ||||
-rw-r--r-- | doc/cli/removing-npm.md (renamed from doc/removing-npm.md) | 0 | ||||
-rw-r--r-- | doc/cli/restart.md (renamed from doc/restart.md) | 0 | ||||
l--------- | doc/cli/rm.md (renamed from doc/rm.md) | 0 | ||||
-rw-r--r-- | doc/cli/root.md (renamed from doc/root.md) | 0 | ||||
-rw-r--r-- | doc/cli/run-script.md (renamed from doc/run-script.md) | 0 | ||||
-rw-r--r-- | doc/cli/scripts.md (renamed from doc/scripts.md) | 0 | ||||
-rw-r--r-- | doc/cli/search.md (renamed from doc/search.md) | 0 | ||||
-rw-r--r-- | doc/cli/semver.md (renamed from doc/semver.md) | 0 | ||||
l--------- | doc/cli/set.md | 1 | ||||
-rw-r--r-- | doc/cli/start.md (renamed from doc/start.md) | 0 | ||||
-rw-r--r-- | doc/cli/stop.md (renamed from doc/stop.md) | 0 | ||||
-rw-r--r-- | doc/cli/submodule.md (renamed from doc/submodule.md) | 0 | ||||
-rw-r--r-- | doc/cli/tag.md (renamed from doc/tag.md) | 0 | ||||
-rw-r--r-- | doc/cli/test.md (renamed from doc/test.md) | 0 | ||||
-rw-r--r-- | doc/cli/uninstall.md (renamed from doc/uninstall.md) | 0 | ||||
-rw-r--r-- | doc/cli/unpublish.md (renamed from doc/unpublish.md) | 0 | ||||
-rw-r--r-- | doc/cli/update.md (renamed from doc/update.md) | 0 | ||||
-rw-r--r-- | doc/cli/version.md (renamed from doc/version.md) | 0 | ||||
-rw-r--r-- | doc/cli/view.md (renamed from doc/view.md) | 0 | ||||
-rw-r--r-- | doc/cli/whoami.md (renamed from doc/whoami.md) | 0 | ||||
-rwxr-xr-x | html/api/GubbleBum-Blocky.ttf | bin | 0 -> 10292 bytes | |||
-rw-r--r-- | html/api/style.css | 336 | ||||
-rw-r--r-- | lib/help-search.js | 14 | ||||
-rw-r--r-- | lib/help.js | 45 | ||||
-rw-r--r-- | npm.js | 1 | ||||
-rw-r--r-- | package.json | 2 | ||||
-rwxr-xr-x | scripts/doc-build.sh | 27 |
111 files changed, 1369 insertions, 51 deletions
diff --git a/.gitignore b/.gitignore index 062b48772..9502d66ca 100644 --- a/.gitignore +++ b/.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 @@ -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" diff --git a/doc/author.md b/doc/api/author.md index b7a53cb66..b7a53cb66 120000 --- a/doc/author.md +++ b/doc/api/author.md diff --git a/doc/api/bin.md b/doc/api/bin.md new file mode 100644 index 000000000..78d147d80 --- /dev/null +++ b/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. diff --git a/doc/api/commands.md b/doc/api/commands.md new file mode 100644 index 000000000..8f1115506 --- /dev/null +++ b/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" + diff --git a/doc/api/config.md b/doc/api/config.md new file mode 100644 index 000000000..c4218a845 --- /dev/null +++ b/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. diff --git a/doc/api/deprecate.md b/doc/api/deprecate.md new file mode 100644 index 000000000..273e1452c --- /dev/null +++ b/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. diff --git a/doc/api/docs.md b/doc/api/docs.md new file mode 100644 index 000000000..2c5fc5e63 --- /dev/null +++ b/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. diff --git a/doc/api/edit.md b/doc/api/edit.md new file mode 100644 index 000000000..b13fbb857 --- /dev/null +++ b/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. diff --git a/doc/api/explore.md b/doc/api/explore.md new file mode 100644 index 000000000..a239f3df3 --- /dev/null +++ b/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. diff --git a/doc/api/find.md b/doc/api/find.md new file mode 120000 index 000000000..5b3debb8f --- /dev/null +++ b/doc/api/find.md @@ -0,0 +1 @@ +ls.md
\ No newline at end of file diff --git a/doc/get.md b/doc/api/get.md index 3dc873736..3dc873736 120000 --- a/doc/get.md +++ b/doc/api/get.md diff --git a/doc/api/help-search.md b/doc/api/help-search.md new file mode 100644 index 000000000..5c00cfc17 --- /dev/null +++ b/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. diff --git a/doc/home.md b/doc/api/home.md index 8828313f5..8828313f5 120000 --- a/doc/home.md +++ b/doc/api/home.md diff --git a/doc/api/init.md b/doc/api/init.md new file mode 100644 index 000000000..5afc11b3b --- /dev/null +++ b/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) diff --git a/doc/api/install.md b/doc/api/install.md new file mode 100644 index 000000000..12f665a76 --- /dev/null +++ b/doc/api/install.md @@ -0,0 +1,19 @@ +npm-install(3) -- install a package programmatically +==================================================== + +## SYNOPSIS + + npm.commands.install([where,] packages, callback) + +## DESCRIPTION + +This acts much the same ways as installing on the command-line. + +The 'where' parameter is optional and only used internally, and it specifies +where the packages should be installed to. + +The 'packages' parameter is an array of strings. Each element in the array is +the name of a package to be installed. + +Finally, 'callback' is a function that will be called when all packages have been +installed or when an error has been encountered. diff --git a/doc/api/link.md b/doc/api/link.md new file mode 100644 index 000000000..ad8cefcab --- /dev/null +++ b/doc/api/link.md @@ -0,0 +1,33 @@ +npm-link(3) -- Symlink a package folder +======================================= + +## SYNOPSIS + + npm.command.link(callback) + npm.command.link(packages, callback) + +## DESCRIPTION + +Package linking is a two-step process. + +Without parameters, link will create a globally-installed +symbolic link from `prefix/package-name` to the current folder. + +With a parameters, link will create a symlink from the local `node_modules` +folder to the global symlink. + +When creating tarballs for `npm publish`, the linked packages are +"snapshotted" to their current state by resolving the symbolic links. + +This is +handy for installing your own stuff, so that you can work on it and test it +iteratively without having to continually rebuild. + +For example: + + npm.commands.link(cb) # creates global link from the cwd + # (say redis package) + npm.commands.link('redis', cb) # link-install the package + +Now, any changes to the redis package will be reflected in +the package in the current working directory diff --git a/doc/api/list.md b/doc/api/list.md new file mode 120000 index 000000000..5b3debb8f --- /dev/null +++ b/doc/api/list.md @@ -0,0 +1 @@ +ls.md
\ No newline at end of file diff --git a/doc/api/ln.md b/doc/api/ln.md new file mode 120000 index 000000000..243f99414 --- /dev/null +++ b/doc/api/ln.md @@ -0,0 +1 @@ +link.md
\ No newline at end of file diff --git a/doc/api/load.md b/doc/api/load.md new file mode 100644 index 000000000..a95a6b295 --- /dev/null +++ b/doc/api/load.md @@ -0,0 +1,26 @@ +npm-load(3) -- Load config settings +=================================== + +## SYNOPSIS + + npm.load(conf, cb) + +## DESCRIPTION + +npm.load() must be called before any other function call. Both parameters are +optional, but the second is recommended. + +The first parameter is an object hash of command-line config params, and the +second parameter is a callback that will be called when npm is loaded and +ready to serve. + +The first parameter should follow a similar structure as the package.json +config object. + +For example, to emulate the --dev flag, pass an object that looks like this: + + { + "dev": true + } + +For a list of all the available command-line configs, see `npm help config` diff --git a/doc/api/ls.md b/doc/api/ls.md new file mode 100644 index 000000000..a6c0a1382 --- /dev/null +++ b/doc/api/ls.md @@ -0,0 +1,50 @@ +npm-ls(3) -- List installed packages +====================================== + +## SYNOPSIS + + npm.commands.ls(args, [silent,] callback) + +## DESCRIPTION + +This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure. It will also +return that data using the callback. + +This command does not take any arguments, but args must be defined. +Beyond that, if any arguments are passed in, npm will politely warn that it +does not take positional arguments, though you may set config flags +like with any other command, such as `global` to list global packages. + +It will print out extraneous, missing, and invalid packages. + +If the silent parameter is set to true, nothing will be output to the screen, +but the data will still be returned. + +## CONFIGURATION + +### long + +* Default: false +* Type: Boolean + +Show extended information. + +### parseable + +* Default: false +* Type: Boolean + +Show parseable output instead of tree view. + +### global + +* Default: false +* Type: Boolean + +List packages in the global install prefix instead of in the current +project. + +Note, if parseable is set or long isn't set, then duplicates will be trimmed. +This means that if a submodule a same dependency as a parent module, then the +dependency will only be output once. diff --git a/doc/api/npm.md b/doc/api/npm.md new file mode 100644 index 000000000..22045fab4 --- /dev/null +++ b/doc/api/npm.md @@ -0,0 +1,30 @@ +npm(3) -- node package manager +============================== + +## SYNOPSIS + + var npm = require("npm") + npm.load(configObject, function (er, npm) { + // use the npm object, now that it's loaded. + }) + +## DESCRIPTION + +Since you're looking at this man page, you are probably wanting to integrate +npm into your program. To find documentation of the npm command line +client, then use `npm help npm` or `man npm`. + +Every time you use npm, you must call `npm.load()` with an object hash of +command-line configs. After that, each of the functions are accessible in the +commands object: `npm.commands.<cmd>` Check out `npm help config` or +for all available options. + +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. + +Configs cannot currently be set on a per function basis, as each call to +npm.config.set will change the value for *all* npm commands in that process. + +To find API documentation for a specific command, try the man pages first. + diff --git a/doc/api/outdated.md b/doc/api/outdated.md new file mode 100644 index 000000000..89f4cf6fa --- /dev/null +++ b/doc/api/outdated.md @@ -0,0 +1,13 @@ +npm-outdated(3) -- Check for outdated packages +============================================== + +## SYNOPSIS + + npm.commands.outdated([packages,] callback) + +## DESCRIPTION + +This command will check the registry to see if the specified packages are +currently outdated. + +If the 'packages' parameter is left out, npm will check all packages. diff --git a/doc/api/owner.md b/doc/api/owner.md new file mode 100644 index 000000000..de203c072 --- /dev/null +++ b/doc/api/owner.md @@ -0,0 +1,31 @@ +npm-owner(3) -- Manage package owners +===================================== + +## SYNOPSIS + + npm.commands.owner(args, callback) + +## DESCRIPTION + +The first element of the 'args' parameter defines what to do, and the subsequent +elements depend on the action. Possible values for the action are (order of +parameters are given in parenthesis): + +* ls (package): + List all the users who have access to modify a package and push new versions. + Handy when you need to know who to bug for help. +* add (user, package): + Add a new user as a maintainer of a package. This user is enabled to modify + metadata, publish new versions, and add other owners. +* rm (user, package): + Remove a user from the package owner list. This immediately revokes their + privileges. + +Note that there is only one level of access. Either you can modify a package, +or you can't. Future versions may contain more fine-grained access levels, but +that is not implemented at this time. + +## SEE ALSO + +* npm-publish(3) +* npm-registry(1) diff --git a/doc/api/pack.md b/doc/api/pack.md new file mode 100644 index 000000000..cb339c0c4 --- /dev/null +++ b/doc/api/pack.md @@ -0,0 +1,19 @@ +npm-pack(3) -- Create a tarball from a package +============================================== + +## SYNOPSIS + + npm.commands.pack([packages,] callback) + +## DESCRIPTION + +For anything that's installable (that is, a package folder, tarball, +tarball url, name@tag, name@version, or name), this command will fetch +it to the cache, and then copy the tarball to the current working +directory as `<name>-<version>.tgz`, and then write the filenames out to +stdout. + +If the same package is specified multiple times, then the file will be +overwritten the second time. + +If no arguments are supplied, then npm packs the current package folder. diff --git a/doc/api/prefix.md b/doc/api/prefix.md new file mode 100644 index 000000000..806dd4b6c --- /dev/null +++ b/doc/api/prefix.md @@ -0,0 +1,15 @@ +npm-prefix(3) -- Display prefix +=============================== + +## SYNOPSIS + + npm.commands.prefix(args, callback) + +## DESCRIPTION + +Print the prefix to standard out. + +'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 diff --git a/doc/api/prune.md b/doc/api/prune.md new file mode 100644 index 000000000..2a4f17748 --- /dev/null +++ b/doc/api/prune.md @@ -0,0 +1,17 @@ +npm-prune(3) -- Remove extraneous packages +========================================== + +## SYNOPSIS + + npm.commands.prune([packages,] callback) + +## DESCRIPTION + +This command removes "extraneous" packages. + +The first parameter is optional, and it specifies packages to be removed. + +No packages are specified, then all packages will be checked. + +Extraneous packages are packages that are not listed on the parent +package's dependencies list. diff --git a/doc/api/publish.md b/doc/api/publish.md new file mode 100644 index 000000000..a743303f8 --- /dev/null +++ b/doc/api/publish.md @@ -0,0 +1,30 @@ +npm-publish(3) -- Publish a package +=================================== + +## SYNOPSIS + + npm.commands.publish([packages,] callback) + +## DESCRIPTION + +Publishes a package to the registry so that it can be installed by name. +Possible values in the 'packages' array are: + +* `<folder>`: + A folder containing a package.json file + +* `<tarball>`: + A url or file path to a gzipped tar archive containing a single folder + with a package.json file inside. + +If the package array is empty, npm will try to publish something in the +current working directory. + +This command could fails if one of the packages specified already exists in +the registry. Overwrites when the "force" environment variable is set. + +## SEE ALSO + +* npm-registry(1) +* npm-adduser(1) +* npm-owner(3) diff --git a/doc/api/rebuild.md b/doc/api/rebuild.md new file mode 100644 index 000000000..8b8989806 --- /dev/null +++ b/doc/api/rebuild.md @@ -0,0 +1,16 @@ +npm-rebuild(3) -- Rebuild a package +=================================== + +## SYNOPSIS + + npm.commands.rebuild([packages,] callback) + +## DESCRIPTION + +This command runs the `npm build` command on each of the matched packages. This is useful +when you install a new version of node, and must recompile all your C++ addons with +the new binary. If no 'packages' parameter is specify, every package will be rebuilt. + +## CONFIGURATION + +See `npm help build` diff --git a/doc/api/restart.md b/doc/api/restart.md new file mode 100644 index 000000000..c40704438 --- /dev/null +++ b/doc/api/restart.md @@ -0,0 +1,22 @@ +npm-restart(3) -- Start a package +================================= + +## SYNOPSIS + + npm.commands.restart(packages, callback) + +## DESCRIPTION + +This runs a package's "restart" script, if one was provided. +Otherwise it runs package's "stop" script, if one was provided, and then +the "start" script. + +If no version is specified, then it restarts the "active" version. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. + +## SEE ALSO + +* npm-start(3) +* npm-stop(3) diff --git a/doc/api/rm.md b/doc/api/rm.md new file mode 120000 index 000000000..32d3b511f --- /dev/null +++ b/doc/api/rm.md @@ -0,0 +1 @@ +uninstall.md
\ No newline at end of file diff --git a/doc/api/root.md b/doc/api/root.md new file mode 100644 index 000000000..1c3ab5640 --- /dev/null +++ b/doc/api/root.md @@ -0,0 +1,15 @@ +npm-root(3) -- Display npm root +=============================== + +## SYNOPSIS + + npm.commands.root(args, callback) + +## DESCRIPTION + +Print the effective `node_modules` folder to standard out. + +'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. diff --git a/doc/api/run-script.md b/doc/api/run-script.md new file mode 100644 index 000000000..f15900ecb --- /dev/null +++ b/doc/api/run-script.md @@ -0,0 +1,27 @@ +npm-run-script(3) -- Run arbitrary package scripts +================================================== + +## SYNOPSIS + + npm.commands.run-script(args, callback) + +## DESCRIPTION + +This runs an arbitrary command from a package's "scripts" object. + +It is used by the test, start, restart, and stop commands, but can be +called directly, as well. + +The 'args' parameter is an array of strings. Behavior depends on the number +of elements. If there is only one element, npm assumes that the element +represents a command to be run on the local repository. If there is more than +one element, then the first is assumed to be the package and the second is +assumed to be the command to run. All other elements are ignored. + +## SEE ALSO + +* npm-scripts(1) +* npm-test(3) +* npm-start(3) +* npm-restart(3) +* npm-stop(3) diff --git a/doc/api/search.md b/doc/api/search.md new file mode 100644 index 000000000..30651d76a --- /dev/null +++ b/doc/api/search.md @@ -0,0 +1,35 @@ +npm-search(3) -- Search for packages +==================================== + +## SYNOPSIS + + npm.commands.search(searchTerms, [silent,] [staleness,] callback) + +## DESCRIPTION + +Search the registry for packages matching the search terms. The available parameters are: + +* searchTerms: + Array of search terms. These terms are case-insensitive. +* silent: + If true, npm will not log anything to the console. +* staleness: + This is the threshold for stale packages. "Fresh" packages are not refreshed + from the registry. This value is measured in seconds. +* callback: + Returns an object where each key is the name of a package, and the value + is information about that package along with a 'words' property, which is + a space-delimited string of all of the interesting words in that package. + The only properties included are those that are searched, which generally include: + + * name + * description + * maintainers + * url + * keywords + +A search on the registry excludes any result that does not match all of the +search terms. It also removes any items from the results that contain an +excluded term (the "searchexclude" config). The search is case insensitive +and doesn't try to read your mind (it doesn't do any verb tense matching or the +like). diff --git a/doc/set.md b/doc/api/set.md index 3dc873736..3dc873736 120000 --- a/doc/set.md +++ b/doc/api/set.md diff --git a/doc/api/start.md b/doc/api/start.md new file mode 100644 index 000000000..74491146a --- /dev/null +++ b/doc/api/start.md @@ -0,0 +1,13 @@ +npm-start(3) -- Start a package +=============================== + +## SYNOPSIS + + npm.commands.start(packages, callback) + +## DESCRIPTION + +This runs a package's "start" script, if one was provided. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/doc/api/stop.md b/doc/api/stop.md new file mode 100644 index 000000000..0f8333d35 --- /dev/null +++ b/doc/api/stop.md @@ -0,0 +1,13 @@ +npm-stop(3) -- Stop a package +============================= + +## SYNOPSIS + + npm.commands.stop(packages, callback) + +## DESCRIPTION + +This runs a package's "stop" script, if one was provided. + +npm can run stop on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/doc/api/submodule.md b/doc/api/submodule.md new file mode 100644 index 000000000..2d8bafaa3 --- /dev/null +++ b/doc/api/submodule.md @@ -0,0 +1,28 @@ +npm-submodule(3) -- Add a package as a git submodule +==================================================== + +## SYNOPSIS + + npm.commands.submodule(packages, callback) + +## DESCRIPTION + +For each package specified, npm will check if it has a git repository url +in its package.json description then add it as a git submodule at +`node_modules/<pkg name>`. + +This is a convenience only. From then on, it's up to you to manage +updates by using the appropriate git commands. npm will stubbornly +refuse to update, modify, or remove anything with a `.git` subfolder +in it. + +This command also does not install missing dependencies, if the package +does not include them in its git repository. If `npm ls` reports that +things are missing, you can either install, link, or submodule them yourself, +or you can do `npm explore <pkgname> -- npm install` to install the +dependencies into the submodule folder. + +## SEE ALSO + +* npm help json +* git help submodule diff --git a/doc/api/tag.md b/doc/api/tag.md new file mode 100644 index 000000000..b5a3d7faa --- /dev/null +++ b/doc/api/tag.md @@ -0,0 +1,23 @@ +npm-tag(3) -- Tag a published version +===================================== + +## SYNOPSIS + + npm.commands.tag(package@version, tag, callback) + +## DESCRIPTION + +Tags the specified version of the package with the specified tag, or the +`--tag` config if not specified. + +The 'package@version' is an array of strings, but only the first two elements are +currently used. + +The first element must be in the form package@version, where package +is the package name and version is the version number (much like installing a +specific version). + +The second element is the name of the tag to tag this version with. If this +parameter is missing or falsey (empty), the default froom the config will be +used. For more information about how to set this config, check +`man 3 npm-config` for programmatic usage or `man npm-config` for cli usage. diff --git a/doc/api/test.md b/doc/api/test.md new file mode 100644 index 000000000..bc48dcc35 --- /dev/null +++ b/doc/api/test.md @@ -0,0 +1,16 @@ +npm-test(3) -- Test a package +============================= + +## SYNOPSIS + + npm.commands.test(packages, callback) + +## DESCRIPTION + +This runs a package's "test" script, if one was provided. + +To run tests as a condition of installation, set the `npat` config to +true. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/doc/api/uninstall.md b/doc/api/uninstall.md new file mode 100644 index 000000000..4505295b3 --- /dev/null +++ b/doc/api/uninstall.md @@ -0,0 +1,16 @@ +npm-uninstall(3) -- uninstall a package programmatically +======================================================== + +## SYNOPSIS + + npm.commands.uninstall(packages, callback) + +## DESCRIPTION + +This acts much the same ways as uninstalling on the command-line. + +The 'packages' parameter is an array of strings. Each element in the array is +the name of a package to be uninstalled. + +Finally, 'callback' is a function that will be called when all packages have been +uninstalled or when an error has been encountered. diff --git a/doc/api/unpublish.md b/doc/api/unpublish.md new file mode 100644 index 000000000..6cbc5c1f3 --- /dev/null +++ b/doc/api/unpublish.md @@ -0,0 +1,20 @@ +npm-unpublish(3) -- Remove a package from the registry +====================================================== + +## SYNOPSIS + + npm.commands.unpublish(package, callback) + +## DESCRIPTION + +This removes a package version from the registry, deleting its +entry and removing the tarball. + +The package parameter must be defined. + +Only the first element in the package parameter is used. If there is no first +element, then npm assumes that the package at the current working directory +is what is meant. + +If no version is specified, or if all versions are removed then +the root package entry is removed from the registry entirely. diff --git a/doc/api/update.md b/doc/api/update.md new file mode 100644 index 000000000..bf02fd3c8 --- /dev/null +++ b/doc/api/update.md @@ -0,0 +1,11 @@ +npm-update(3) -- Update a package +================================= + +## SYNOPSIS + npm.commands.update(packages, callback) + +# DESCRIPTION + +Updates a package, upgrading it to the latest version. It also installs any missing packages. + +The 'packages' argument is an array of packages to update. The 'callback' parameter will be called when done or when an error occurs. diff --git a/doc/api/version.md b/doc/api/version.md new file mode 100644 index 000000000..bd40102c4 --- /dev/null +++ b/doc/api/version.md @@ -0,0 +1,18 @@ +npm-version(3) -- Bump a package version +======================================== + +## SYNOPSIS + + npm.commands.version(newversion, callback) + +## DESCRIPTION + +Run this in a package directory to bump the version and write the new +data back to the package.json file. + +If run in a git repo, it will also create a version commit and tag, and +fail if the repo is not clean. + +Like all other commands, this function takes a string array as its first +parameter. The difference, however, is this function will fail if it does +not have exactly one element. The only element should be a version number. diff --git a/doc/api/view.md b/doc/api/view.md new file mode 100644 index 000000000..4605e407c --- /dev/null +++ b/doc/api/view.md @@ -0,0 +1,82 @@ +npm-view(3) -- View registry info +================================= + +## SYNOPSIS + + npm.commands.view(args, [silent,] callback) + +## DESCRIPTION + +This command shows data about a package and prints it to the stream +referenced by the `outfd` config, which defaults to stdout. + +The "args" parameter is an ordered list that closely resembles the command-line +usage. The elements should be ordered such that the first element is +the package and version (package@version). The version is optional. After that, +the rest of the parameters are fields with optional subfields ("field.subfield") +which can be used to get only the information desired from the registry. + +The callback will be passed all of the data returned by the query. + +For example, to get the package registry entry for the `connect` package, +you can do this: + + npm.commands.view(["connect"], callback) + +If no version is specified, "latest" is assumed. + +Field names can be specified after the package descriptor. +For example, to show the dependencies of the `ronn` package at version +0.3.5, you could do the following: + + npm.commands.view(["ronn@0.3.5", "dependencies"], callback) + +You can view child field by separating them with a period. +To view the git repository URL for the latest version of npm, you could +do this: + + npm.commands.view(["npm", "repository.url"], callback) + +For fields that are arrays, requesting a non-numeric field will return +all of the values from the objects in the list. For example, to get all +the contributor names for the "express" project, you can do this: + + npm.commands.view(["express", "contributors.email"], callback) + +You may also use numeric indices in square braces to specifically select +an item in an array field. To just get the email address of the first +contributor in the list, you can do this: + + npm.commands.view(["express", "contributors[0].email"], callback) + +Multiple fields may be specified, and will be printed one after another. +For exampls, to get all the contributor names and email addresses, you +can do this: + + npm.commands.view(["express", "contributors.name", "contributors.email"], callback) + +"Person" fields are shown as a string if they would be shown as an +object. So, for example, this will show the list of npm contributors in +the shortened string format. (See `npm help json` for more on this.) + + npm.commands.view(["npm", "contributors"], callback) + +If a version range is provided, then data will be printed for every +matching version of the package. This will show which version of jsdom +was required by each matching version of yui3: + + npm.commands.view(["yui3@'>0.5.4'", "dependencies.jsdom"], callback) + +## OUTPUT + +If only a single string field for a single version is output, then it +will not be colorized or quoted, so as to enable piping the output to +another command. + +If the version range matches multiple versions, than each printed value +will be prefixed with the version it applies to. + +If multiple fields are requested, than each of them are prefixed with +the field name. + +Console output can be disabled by setting the 'silent' parameter to true. diff --git a/doc/api/whoami.md b/doc/api/whoami.md new file mode 100644 index 000000000..598a1ab1a --- /dev/null +++ b/doc/api/whoami.md @@ -0,0 +1,15 @@ +npm-whoami(3) -- Display npm username +===================================== + +## SYNOPSIS + + npm.commands.whoami(args, callback) + +## DESCRIPTION + +Print the `username` config to standard output. + +'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 diff --git a/doc/adduser.md b/doc/cli/adduser.md index 51aa6f6a3..51aa6f6a3 100644 --- a/doc/adduser.md +++ b/doc/cli/adduser.md diff --git a/doc/cli/author.md b/doc/cli/author.md new file mode 120000 index 000000000..b7a53cb66 --- /dev/null +++ b/doc/cli/author.md @@ -0,0 +1 @@ +owner.md
\ No newline at end of file diff --git a/doc/bin.md b/doc/cli/bin.md index 2c2e7c477..2c2e7c477 100644 --- a/doc/bin.md +++ b/doc/cli/bin.md diff --git a/doc/build.md b/doc/cli/build.md index 978f4a6d6..978f4a6d6 100644 --- a/doc/build.md +++ b/doc/cli/build.md diff --git a/doc/bundle.md b/doc/cli/bundle.md index 69b3d83e4..69b3d83e4 100644 --- a/doc/bundle.md +++ b/doc/cli/bundle.md diff --git a/doc/cache.md b/doc/cli/cache.md index 1fa128ad4..1fa128ad4 100644 --- a/doc/cache.md +++ b/doc/cli/cache.md diff --git a/doc/changelog.md b/doc/cli/changelog.md index 0115405ca..0115405ca 100644 --- a/doc/changelog.md +++ b/doc/cli/changelog.md diff --git a/doc/coding-style.md b/doc/cli/coding-style.md index f0640c85c..f0640c85c 100644 --- a/doc/coding-style.md +++ b/doc/cli/coding-style.md diff --git a/doc/completion.md b/doc/cli/completion.md index 48bc50fd8..48bc50fd8 100644 --- a/doc/completion.md +++ b/doc/cli/completion.md diff --git a/doc/config.md b/doc/cli/config.md index 238d714a9..238d714a9 100644 --- a/doc/config.md +++ b/doc/cli/config.md diff --git a/doc/deprecate.md b/doc/cli/deprecate.md index 925337f21..925337f21 100644 --- a/doc/deprecate.md +++ b/doc/cli/deprecate.md diff --git a/doc/developers.md b/doc/cli/developers.md index 0f0f94c58..0f0f94c58 100644 --- a/doc/developers.md +++ b/doc/cli/developers.md diff --git a/doc/docs.md b/doc/cli/docs.md index 26b2455dd..26b2455dd 100644 --- a/doc/docs.md +++ b/doc/cli/docs.md diff --git a/doc/edit.md b/doc/cli/edit.md index 9eaccfc54..9eaccfc54 100644 --- a/doc/edit.md +++ b/doc/cli/edit.md diff --git a/doc/explore.md b/doc/cli/explore.md index 00701b392..00701b392 100644 --- a/doc/explore.md +++ b/doc/cli/explore.md diff --git a/doc/faq.md b/doc/cli/faq.md index 15bb0c637..15bb0c637 100644 --- a/doc/faq.md +++ b/doc/cli/faq.md diff --git a/doc/cli/find.md b/doc/cli/find.md new file mode 120000 index 000000000..9b687d1c1 --- /dev/null +++ b/doc/cli/find.md @@ -0,0 +1 @@ +search.md
\ No newline at end of file diff --git a/doc/folders.md b/doc/cli/folders.md index 2f0cfd2e6..2f0cfd2e6 100644 --- a/doc/folders.md +++ b/doc/cli/folders.md diff --git a/doc/cli/get.md b/doc/cli/get.md new file mode 120000 index 000000000..3dc873736 --- /dev/null +++ b/doc/cli/get.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/doc/global.md b/doc/cli/global.md index c3598dd7d..c3598dd7d 120000 --- a/doc/global.md +++ b/doc/cli/global.md diff --git a/doc/help-search.md b/doc/cli/help-search.md index 9c16901eb..9c16901eb 100644 --- a/doc/help-search.md +++ b/doc/cli/help-search.md diff --git a/doc/cli/home.md b/doc/cli/home.md new file mode 120000 index 000000000..8828313f5 --- /dev/null +++ b/doc/cli/home.md @@ -0,0 +1 @@ +docs.md
\ No newline at end of file diff --git a/doc/init.md b/doc/cli/init.md index 39297b4c4..39297b4c4 100644 --- a/doc/init.md +++ b/doc/cli/init.md diff --git a/doc/install.md b/doc/cli/install.md index 22eb8234e..22eb8234e 100644 --- a/doc/install.md +++ b/doc/cli/install.md diff --git a/doc/json.md b/doc/cli/json.md index 068ddf977..068ddf977 100644 --- a/doc/json.md +++ b/doc/cli/json.md diff --git a/doc/link.md b/doc/cli/link.md index dd54792e2..dd54792e2 100644 --- a/doc/link.md +++ b/doc/cli/link.md diff --git a/doc/list.md b/doc/cli/list.md index 596349a81..596349a81 100644 --- a/doc/list.md +++ b/doc/cli/list.md diff --git a/doc/ln.md b/doc/cli/ln.md index 52ae308ef..52ae308ef 120000 --- a/doc/ln.md +++ b/doc/cli/ln.md diff --git a/doc/ls.md b/doc/cli/ls.md index 51a383bf1..51a383bf1 120000 --- a/doc/ls.md +++ b/doc/cli/ls.md diff --git a/doc/npm.md b/doc/cli/npm.md index ac7e5e4c3..ac7e5e4c3 100644 --- a/doc/npm.md +++ b/doc/cli/npm.md diff --git a/doc/outdated.md b/doc/cli/outdated.md index 78df4a8b3..78df4a8b3 100644 --- a/doc/outdated.md +++ b/doc/cli/outdated.md diff --git a/doc/owner.md b/doc/cli/owner.md index 8365da379..8365da379 100644 --- a/doc/owner.md +++ b/doc/cli/owner.md diff --git a/doc/pack.md b/doc/cli/pack.md index 98d8c81c5..98d8c81c5 100644 --- a/doc/pack.md +++ b/doc/cli/pack.md diff --git a/doc/prefix.md b/doc/cli/prefix.md index f6247cab1..f6247cab1 100644 --- a/doc/prefix.md +++ b/doc/cli/prefix.md diff --git a/doc/prune.md b/doc/cli/prune.md index 8c4b957e6..8c4b957e6 100644 --- a/doc/prune.md +++ b/doc/cli/prune.md diff --git a/doc/publish.md b/doc/cli/publish.md index 621932f07..621932f07 100644 --- a/doc/publish.md +++ b/doc/cli/publish.md diff --git a/doc/rebuild.md b/doc/cli/rebuild.md index 6985a7bdd..6985a7bdd 100644 --- a/doc/rebuild.md +++ b/doc/cli/rebuild.md diff --git a/doc/registry.md b/doc/cli/registry.md index 8073ea082..8073ea082 100644 --- a/doc/registry.md +++ b/doc/cli/registry.md diff --git a/doc/removing-npm.md b/doc/cli/removing-npm.md index bedd28a2f..bedd28a2f 100644 --- a/doc/removing-npm.md +++ b/doc/cli/removing-npm.md diff --git a/doc/restart.md b/doc/cli/restart.md index 6139dbeef..6139dbeef 100644 --- a/doc/restart.md +++ b/doc/cli/restart.md diff --git a/doc/rm.md b/doc/cli/rm.md index a9423dfac..a9423dfac 120000 --- a/doc/rm.md +++ b/doc/cli/rm.md diff --git a/doc/root.md b/doc/cli/root.md index 3e4199541..3e4199541 100644 --- a/doc/root.md +++ b/doc/cli/root.md diff --git a/doc/run-script.md b/doc/cli/run-script.md index 41ef5e787..41ef5e787 100644 --- a/doc/run-script.md +++ b/doc/cli/run-script.md diff --git a/doc/scripts.md b/doc/cli/scripts.md index 64b3ec41a..64b3ec41a 100644 --- a/doc/scripts.md +++ b/doc/cli/scripts.md diff --git a/doc/search.md b/doc/cli/search.md index 3b15e9b07..3b15e9b07 100644 --- a/doc/search.md +++ b/doc/cli/search.md diff --git a/doc/semver.md b/doc/cli/semver.md index 7eb224063..7eb224063 100644 --- a/doc/semver.md +++ b/doc/cli/semver.md diff --git a/doc/cli/set.md b/doc/cli/set.md new file mode 120000 index 000000000..3dc873736 --- /dev/null +++ b/doc/cli/set.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/doc/start.md b/doc/cli/start.md index cc897bbc0..cc897bbc0 100644 --- a/doc/start.md +++ b/doc/cli/start.md diff --git a/doc/stop.md b/doc/cli/stop.md index 1ab3e9975..1ab3e9975 100644 --- a/doc/stop.md +++ b/doc/cli/stop.md diff --git a/doc/submodule.md b/doc/cli/submodule.md index 13ab1edd9..13ab1edd9 100644 --- a/doc/submodule.md +++ b/doc/cli/submodule.md diff --git a/doc/tag.md b/doc/cli/tag.md index 2f1ca4373..2f1ca4373 100644 --- a/doc/tag.md +++ b/doc/cli/tag.md diff --git a/doc/test.md b/doc/cli/test.md index bc634efbf..bc634efbf 100644 --- a/doc/test.md +++ b/doc/cli/test.md diff --git a/doc/uninstall.md b/doc/cli/uninstall.md index f7f743fae..f7f743fae 100644 --- a/doc/uninstall.md +++ b/doc/cli/uninstall.md diff --git a/doc/unpublish.md b/doc/cli/unpublish.md index 0f4446c4e..0f4446c4e 100644 --- a/doc/unpublish.md +++ b/doc/cli/unpublish.md diff --git a/doc/update.md b/doc/cli/update.md index 1de49f2e2..1de49f2e2 100644 --- a/doc/update.md +++ b/doc/cli/update.md diff --git a/doc/version.md b/doc/cli/version.md index 2904a6ae2..2904a6ae2 100644 --- a/doc/version.md +++ b/doc/cli/version.md diff --git a/doc/view.md b/doc/cli/view.md index 5ec9dc0ac..5ec9dc0ac 100644 --- a/doc/view.md +++ b/doc/cli/view.md diff --git a/doc/whoami.md b/doc/cli/whoami.md index 7c39b1624..7c39b1624 100644 --- a/doc/whoami.md +++ b/doc/cli/whoami.md diff --git a/html/api/GubbleBum-Blocky.ttf b/html/api/GubbleBum-Blocky.ttf Binary files differnew file mode 100755 index 000000000..8eac02f7a --- /dev/null +++ b/html/api/GubbleBum-Blocky.ttf diff --git a/html/api/style.css b/html/api/style.css new file mode 100644 index 000000000..220d162d6 --- /dev/null +++ b/html/api/style.css @@ -0,0 +1,336 @@ + +/* reset */ +* { + margin:0; + padding:0; + border:none; + font-family:inherit; + font-size:inherit; + font-weight:inherit; +} +:target::before { + content:" >>> "; + position:absolute; + display:block; + opacity:0.5; + color:#f00; + margin:0 0 0 -2em; +} +abbr, acronym { + border-bottom:1px dotted #aaa; +} +kbd, code, pre { + font-family:monospace; + margin:0; + font-size:18px; + line-height:24px; + background:#eee; + outline:1px solid #ccc; +} +kbd code, kbd pre, kbd kbd, +pre code, pre pre, pre kbd, +code code, code pre, code kbd { outline: none } +.dollar::before { + content:"$ "; + display:inline; +} +p, ul, ol, dl, pre { + margin:30px 0; + line-height:30px; +} +hr { + margin:30px auto 29px; + width:66%; + height:1px; + background:#aaa; +} +pre { + display:block; +} +dd :first-child { + margin-top:0; +} + +body { + quotes:"“" "”" "‘" "’"; + width:666px; + margin:30px auto 120px; + font-family:Times New Roman, serif; + font-size:20px; + background:#fff; + line-height:30px; + color:#111; +} + +blockquote { + position:relative; + font-size:16px; + line-height:30px; + font-weight:bold; + width:85%; + margin:0 auto; +} +blockquote::before { + font-size:90px; + display:block; + position:absolute; + top:20px; + right:100%; + content:"“"; + padding-right:10px; + color:#ccc; +} +.source cite::before { + content:"— "; +} +.source { + padding-left:20%; + margin-top:30px; +} +.source cite span { + font-style:normal; +} +blockquote p { + margin-bottom:0; +} +.quote blockquote { + font-weight:normal; +} + +h1, h2, h3, h4, h5, h6, dt, #header { + font-family:serif; + font-size:20px; + font-weight:bold; +} +h2 { + background:#eee; +} +h1, h2 { + line-height:40px; +} + +i, em, cite { + font-style:italic; +} +b, strong { + font-weight:bold; +} +i, em, cite, b, strong, small { + line-height:28px; +} +small, .small, .small *, aside { + font-style:italic; + color:#669; + font-size:18px; +} +spall a, .small a { + text-decoration:underline; +} +del { + text-decoration:line-through; +} +ins { + text-decoration:underline; +} +.alignright { display:block; float:right; margin-left:1em; } +.alignleft { display:block; float:left; margin-right:1em; } + +q:before, q q q:before, q q q q q:before, q q q q q q q:before { content:"“"; } +q q:before, q q q q:before, q q q q q q:before, q q q q q q q q:before { content:"‘"; } +q:after, q q q:after, q q q q q:after, q q q q q q q:after { content:"”"; } +q q:after, q q q q:after, q q q q q q:after, q q q q q q q q:after { content:"’"; } + +a { color:#00f; text-decoration:none; } +a:visited { color:#636; } +a:hover, a:active { color:#900!important; text-decoration:underline; } + +h1 { + font-weight:bold; + background:#fff; +} +h1 a, h1 a:visited { + font-family:gubblefont, GubbleBum Blocky, GubbleBum, monospace; + font-size:60px; + color:#900; + display:block; +} +h1 a:focus, h1 a:hover, h1 a:active { + color:#f00!important; + text-decoration:none; +} + +.navigation { + display:table; + width:100%; + margin:0 0 30px 0; + position:relative; +} +#nav-above { + margin-bottom:0; +} +.navigation .nav-previous { + display:table-cell; + text-align:left; + width:50%; +} +/* hang the » and « off into the margins */ +.navigation .nav-previous a:before, .navigation .nav-next a:after { + content: "«"; + display:block; + height:30px; + margin-bottom:-30px; + text-decoration:none; + margin-left:-15px; +} +.navigation .nav-next a:after { + content: "»"; + text-align:right; + margin-left:0; + margin-top:-30px; + margin-right:-15px; +} + + +.navigation .nav-next { + display:table-cell; + text-align:right; + width:50%; +} +.navigation a { + display:block; + width:100%; + height:100%; +} + +input, button, textarea { + border:0; + line-height:30px; +} +textarea { + height:300px; +} +input { + height:30px; + line-height:30px; +} +input.submit, input#submit, input.button, button, input[type=submit] { + cursor:hand; cursor:pointer; + outline:1px solid #ccc; +} + +#wrapper { + margin-bottom:90px; + position:relative; + z-index:1; + *zoom:1; + background:#fff; +} +#wrapper:after { + display:block; + content:"."; + visibility:hidden; + width:0; + height:0; + clear:both; +} + +.sidebar .xoxo > li { + float:left; + width:50%; +} +.sidebar li { + list-style:none; +} +.sidebar #elsewhere { + margin-left:-10%; + margin-right:-10%; +} +.sidebar #rss-links, .sidebar #twitter-feeds { + float:right; + clear:right; + width:20%; +} +.sidebar #comment { + clear:both; + float:none; + width:100%; +} +.sidebar #search { + clear:both; + float:none; + width:100%; +} +.sidebar #search h2 { + margin-left:40%; +} +.sidebar #search #s { + width:90%; + float:left; +} +.sidebar #search #searchsubmit { + width:10%; + float:right; +} +.sidebar * { + font-size:15px; + line-height:30px; +} + +#footer, #footer * { + text-align:right; + font-size:16px; + color:#ccc; + font-style:italic; + word-spacing:1em; +} + +#toc { + position:absolute; + top:0; + right:0; + padding:40px 0 40px 20px; + margin:0; + width:200px; + opacity:0.2; + z-index:-1; +} +#toc:hover { + opacity:1; + background:#fff; + z-index:999; +} +#toc ul { + padding:0; + margin:0; +} +#toc, #toc li { + list-style-type:none; + font-size:15px; + line-height:15px; +} +#toc li { + padding:0 0 0 10px; +} +#toc li a { + position:relative; + display:block; +} + +@font-face { + font-family:gubblefont; + src: url(./GubbleBum-Blocky.ttf) format("truetype"); +} + +@media print { + a[href] { + color:inherit; + } + a[href]:after { + white-space:nowrap; + content:" " attr(href); + } + a[href^=\#], .navigation { + display:none; + } +} + diff --git a/lib/help-search.js b/lib/help-search.js index e36dd7bab..f35b6eee8 100644 --- a/lib/help-search.js +++ b/lib/help-search.js @@ -5,7 +5,8 @@ var fs = require("graceful-fs") , output = require("./utils/output.js") , path = require("path") , asyncMap = require("slide").asyncMap - , docsPath = path.join(__dirname, "..", "doc") + , cliDocsPath = path.join(__dirname, "..", "doc", "cli") + , apiDocsPath = path.join(__dirname, "..", "doc", "api") , log = require("./utils/log.js") , npm = require("../npm.js") @@ -15,6 +16,15 @@ function helpSearch (args, silent, cb) { if (typeof cb !== "function") cb = silent, silent = false if (!args.length) return cb(helpSearch.usage) + // see if we're actually searching the api docs. + var argv = npm.config.get("argv").cooked + , docsPath = cliDocsPath + , cmd = "help" + if (argv.length && argv[0].indexOf("api") !== -1) { + docsPath = apiDocsPath + cmd = "apihelp" + } + fs.readdir(docsPath, function(er, files) { if (er) return log.er(cb, "Could not load documentation")(er) @@ -122,7 +132,7 @@ function helpSearch (args, silent, cb) { }) var out = results.map(function (res, i, results) { - var out = "npm help "+res.file.replace(/\.md$/, "") + var out = "npm " + cmd + " "+res.file.replace(/\.md$/, "") , r = Object.keys(res.hits).map(function (k) { return k + ":" + res.hits[k] }).sort(function (a, b) { diff --git a/lib/help.js b/lib/help.js index 7b6a6ee52..52c18b97d 100644 --- a/lib/help.js +++ b/lib/help.js @@ -3,7 +3,9 @@ module.exports = help help.completion = function (opts, cb) { if (opts.conf.argv.remain.length > 2) return cb(null, []) - getSections(cb) + var num = 1 + if (-1 !== opts.conf.argv.remain[1].indexOf("api")) num = 3 + getSections(num, cb) } var fs = require("graceful-fs") @@ -11,10 +13,21 @@ var fs = require("graceful-fs") , exec = require("./utils/exec.js") , npm = require("../npm.js") , output = require("./utils/output.js") + , log = require("./utils/log.js") function help (args, cb) { - if (args.length > 1 && args[0]) return npm.commands["help-search"](args, cb) + var num = 1 + , argv = npm.config.get("argv").cooked + if (argv.length && -1 !== argv[0].indexOf("api")) { + num = 3 + } + + if (args.length > 1 && args[0]) { + return npm.commands["help-search"](args, num, cb) + } + var section = args[0] + if (section) { if ( npm.config.get("usage") && npm.commands[section] @@ -23,17 +36,21 @@ function help (args, cb) { npm.config.set("loglevel", "silent") return output.write(npm.commands[section].usage, cb) } - var sectionPath = path.resolve(__dirname, "..", "man1", section+".1") + var sectionPath = path.join( __dirname, "..", "man", "man" + num + , section + "." + num) , htmlPath = path.resolve( __dirname, "..", "html" - , "doc", section+".html" ) + , num === 3 ? "api" : "doc" + , section+".html" ) return fs.stat ( sectionPath , function (e, o) { if (e) return npm.commands["help-search"](args, cb) - var manpath = path.join(__dirname, "..") + var manpath = path.join(__dirname, "..", "man") , env = {} - Object.keys(process.env).forEach(function (i) { env[i] = process.env[i] }) + Object.keys(process.env).forEach(function (i) { + env[i] = process.env[i] + }) env.MANPATH = manpath var viewer = npm.config.get("viewer") switch (viewer) { @@ -55,7 +72,7 @@ function help (args, cb) { } break default: - exec("man", [section], env, true, cb) + exec("man", [num, section], env, true, cb) } } ) @@ -118,12 +135,16 @@ function wrap (arr) { return out.join("\n ").substr(2) } -function getSections(cb) { - fs.readdir(path.join(__dirname, "../man1/"), function (er, files) { +function getSections (num, cb) { + if (typeof cb !== "function") cb = num, num = 1 + + var mp = path.join(__dirname, "../man/man" + num + "/") + , cleaner = new RegExp("\\." + num + "$") + fs.readdir(mp, function (er, files) { if (er) return cb(er) - var sectionList = files.concat("help.1") - .filter(function (s) { return s.match(/\.1$/) }) - .map(function (s) { return s.replace(/\.1$/, '')}) + var sectionList = files.concat("help." + num) + .filter(function (s) { return s.match(cleaner) }) + .map(function (s) { return s.replace(cleaner, "")}) cb(null, sectionList) }) } @@ -70,6 +70,7 @@ var commandCache = {} , "author" : "owner" , "home" : "docs" , "unstar": "star" // same function + , "apihelp" : "help" } , aliasNames = Object.keys(aliases) diff --git a/package.json b/package.json index e11612b99..c859efaed 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ , "web" : "http://github.com/isaacs/npm/issues" } , "directories" : { "doc" : "./doc" - , "man" : "./man1" + , "man" : "./man" , "lib" : "./lib" , "bin" : "./bin" } diff --git a/scripts/doc-build.sh b/scripts/doc-build.sh index 218425de1..9c8fbee64 100755 --- a/scripts/doc-build.sh +++ b/scripts/doc-build.sh @@ -17,6 +17,16 @@ version=$(node cli.js -v) mkdir -p $(dirname $dest) case $dest in + *.[13]) + ./node_modules/.bin/ronn --roff $src \ + | sed "s|@VERSION@|$version|g" \ + | perl -pi -e 's/npm\\-([^\(]*)\(1\)/npm help \1/g' \ + | perl -pi -e 's/npm\\-([^\(]*)\(3\)/npm apihelp \1/g' \ + | perl -pi -e 's/npm\(1\)/npm help npm/g' \ + | perl -pi -e 's/npm\(3\)/npm apihelp npm/g' \ + > $dest + exit $? + ;; *.html) (cat html/dochead.html && \ ./node_modules/.bin/ronn -f $src && \ @@ -26,18 +36,11 @@ case $dest in | sed "s|@VERSION@|$version|g" \ | perl -pi -e 's/<h1>npm(-?[^\(]*\([0-9]\)) -- (.*?)<\/h1>/<h1>npm\1<\/h1> <p>\2<\/p>/g' \ | perl -pi -e 's/npm-npm/npm/g' \ - | perl -pi -e 's/([^"-])(npm-)?README(\(1\))?/\1<a href="README.html">README<\/a>/g' \ - | perl -pi -e 's/<title><a href="README.html">README<\/a><\/title>/<title>README<\/title>/g' \ - | perl -pi -e 's/([^"-])npm-([^\(]+)\(1\)/\1<a href="\2.html">\2<\/a>/g' \ - | perl -pi -e 's/([^"-])npm\(1\)/\1<a href="npm.html">npm<\/a>/g' \ - > $dest - exit $? - ;; - *.1) - ./node_modules/.bin/ronn --roff $src \ - | sed "s|@VERSION@|$version|g" \ - | perl -pi -e 's/npm\\-([^\(]*)\([0-9]\)/npm help \1/g' \ - | perl -pi -e 's/npm\([0-9]\)/npm help npm/g' \ + | perl -pi -e 's/([^"-])(npm-)?README(\(1\))?/\1<a href="..\/doc\/README.html">README<\/a>/g' \ + | perl -pi -e 's/<title><a href="..\/doc\/README.html">README<\/a><\/title>/<title>README<\/title>/g' \ + | perl -pi -e 's/([^"-])npm-([^\(]+)\(1\)/\1<a href="..\/doc\/\2.html">\2<\/a>/g' \ + | perl -pi -e 's/([^"-])npm-([^\(]+)\(3\)/\1<a href="..\/api\/\2.html">\2<\/a>/g' \ + | perl -pi -e 's/([^"-])npm\(1\)/\1<a href="..\/doc\/npm.html">npm<\/a>/g' \ > $dest exit $? ;; |