Permalink
Browse files

More doc stuff.

  • Loading branch information...
1 parent faaf7e9 commit fe576995c40f87544116ca210e7b21e0484b1c57 @isaacs isaacs committed Sep 25, 2011
Showing with 159 additions and 84 deletions.
  1. +9 −4 doc/api/bin.md
  2. +3 −51 doc/api/commands.md
  3. +35 −16 doc/api/config.md
  4. +15 −3 doc/api/deprecate.md
  5. +95 −10 doc/api/npm.md
  6. +1 −0 doc/cli/npm.md
  7. +1 −0 scripts/doc-build.sh
View
@@ -3,13 +3,18 @@ npm-bin(3) -- Display npm bin folder
## SYNOPSIS
- npm.commands.bin(args, callback)
+ npm.commands.bin(args, cb)
## 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 should not be used programmatically. The logic for
+attaining the bin folder is quite simple.
-This function is not useful programmatically.
+ var bin
+ if (npm.config.get("global")) {
+ bin = path.resolve(npm.prefix, "bin")
+ } else {
+ bin = path.resolve(npm.dir, ".bin")
+ }
View
@@ -3,7 +3,7 @@ npm-commands(3) -- npm commands
## SYNOPSIS
- npm.commands.<command>(args, callback)
+ npm.commands[<command>](args, callback)
## DESCRIPTION
@@ -17,54 +17,6 @@ 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"
+## SEE ALSO
+* npm-index(1)
View
@@ -1,26 +1,45 @@
-npm-config(3) -- Manage the npm configuration file
-==================================================
+npm-config(3) -- Manage the npm configuration files
+===================================================
## SYNOPSIS
npm.commands.config(args, callback)
+ var val = npm.config.get(key)
+ npm.config.set(key, val)
## 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.
+* `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.
+
+To programmatically access npm configuration settings, or set them for
+the duration of a program, use the `npm.config.set` and `npm.config.get`
+functions instead.
+
+## SEE ALSO
+
+* npm(3)
View
@@ -12,9 +12,21 @@ 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
+* `package[@version]`
+
+ The `version` portion is optional, and may be either a range, or a
+ specific version, or a tag.
+
+* `message`
+
+ The warning message that will be printed whenever a user attempts to
+ install the package.
Note that you must be the package owner to deprecate something. See the
`owner` and `adduser` help topics.
+
+## SEE ALSO
+
+* npm-publish(3)
+* npm-unpublish(3)
+* npm-registry(1)
View
@@ -6,25 +6,110 @@ npm(3) -- node package manager
var npm = require("npm")
npm.load(configObject, function (er, npm) {
// use the npm object, now that it's loaded.
+
+ npm.config.set(key, val)
+ val = npm.config.get(key)
+
+ console.log("prefix = %s", npm.prefix)
+
+ npm.commands.install(["package"], cb)
})
+## VERSION
+
+@VERSION@
+
## 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`.
+This is the API documentation for npm.
+To find documentation of the command line
+client, see `npm(1)`.
+
+Prior to using npm's commands,
+`npm.load()` must be called with an object hash of
+top-level configs. In the npm command line client,
+this set of configs is parsed from the command line options. Additional
+configuration params are loaded from two configuration files. See
+`npm-config(1)` for more information.
-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.
+After that, each of the functions are accessible in the
+commands object: `npm.commands.<cmd>`. See `npm-index(1)` for a list of
+all possible commands.
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.
+**strings**. The last argument to any function is a callback. Some
+commands 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.
+To find API documentation for a specific command, run the `npm apihelp`
+command.
+
+## METHODS AND PROPERTIES
+
+* `npm.load(configs, cb)`
+
+ Load the configuration params, and call the `cb` function once the
+ globalconfig and userconfig files have been loaded as well, or on
+ nextTick if they've already been loaded.
+
+* `npm.config`
+
+ An object for accessing npm configuration parameters.
+
+ * `npm.config.get(key)`
+ * `npm.config.set(key, val)`
+ * `npm.config.del(key)`
+
+* `npm.dir` or `npm.root`
+
+ The `node_modules` directory where npm will operate.
+
+* `npm.prefix`
+
+ The prefix where npm is operating. (Most often the current working
+ directory.)
+
+* `npm.cache`
+
+ The place where npm keeps JSON and tarballs it fetches from the
+ registry (or uploads to the registry).
+
+* `npm.tmp`
+
+ npm's temporary working directory.
+
+* `npm.deref`
+
+ Get the "real" name for a command that has either an alias or
+ abbreviation.
+
+## MAGIC
+
+For each of the methods in the `npm.commands` hash, a method is added to
+the npm object, which takes a set of positional string arguments rather
+than an array and a callback.
+
+If the last argument is a callback, then it will use the supplied
+callback. However, if no callback is provided, then it will print out
+the error or results.
+
+For example, this would work in a node repl:
+
+ > npm = require("npm")
+ > npm.load() // wait a sec...
+ > npm.install("dnode", "express")
+
+Note that that *won't* work in a node program, since the `install`
+method will get called before the configuration load is completed.
+
+## ABBREVS
+
+In order to support `npm ins foo` instead of `npm install foo`, the
+`npm.commands` object has a set of abbreviations as well as the full
+method names. Use the `npm.deref` method to find the real name.
+
+For example:
+ var cmd = npm.deref("unp") // cmd === "unpublish"
View
@@ -152,3 +152,4 @@ See npm-changelog(1)
* npm-install(1)
* npm-config(1)
* npm-index(1)
+* npm(3)
View
@@ -41,6 +41,7 @@ case $dest in
| 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' \
+ | perl -pi -e 's/([^"-])npm\(3\)/\1<a href="..\/api\/npm.html">npm<\/a>/g' \
> $dest
exit $?
;;

0 comments on commit fe57699

Please sign in to comment.