Skip to content

Commit

Permalink
docs: better manual page
Browse files Browse the repository at this point in the history
  • Loading branch information
@ruyadorno
ruyadorno committed Nov 24, 2019
1 parent aa52108 commit 58d59c4
Show file tree
Hide file tree
Showing 3 changed files with 314 additions and 72 deletions.
1 change: 1 addition & 0 deletions README.md
View file
Expand Up @@ -155,6 +155,7 @@ These descriptions will be shown anytime you run `ntl`.
Use the `--info` or simply `-i` option in order to display the contents of each script task, like:

```sh
$ ntl -i
⬢ Node Task List
? Select a task to run: (Use arrow keys)
❯ generate-manual › maked-man README.md > man/man1/ntl.1
Expand Down
380 changes: 310 additions & 70 deletions man/man1/ntl.1
View file
@@ -1,72 +1,312 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11.
.TH NTL "1" "November 2019" "ntl 5.0.0" "User Commands"
.TH "ntl" "1" "November 2019" "5.0.0" "Node Task List"
.SH NAME
ntl \- manual page for ntl 5.0.0
.SH DESCRIPTION
.SS "Usage:"
.TP
ntl [<path>]
Build an interactive interface and run any script
.TP
nt [<path>]
Rerun last executed script
.SH OPTIONS
.TP
\fB\-a\fR, \fB\-\-all\fR
Includes pre and post scripts on the list [boolean]
.TP
\fB\-A\fR, \fB\-\-autocomplete\fR
Starts in autocomplete mode [boolean]
.TP
\fB\-D\fR, \fB\-\-debug\fR
Prints to stderr any internal error [boolean]
.TP
\fB\-d\fR, \fB\-\-descriptions\fR
Displays the descriptions of each script [boolean]
.TP
\fB\-o\fR, \fB\-\-descriptions\-only\fR
Limits output to scripts with a description [boolean]
.TP
\fB\-h\fR, \fB\-\-help\fR
Shows this help message [boolean]
.TP
\fB\-i\fR, \fB\-\-info\fR
Displays the contents of each script [boolean]
.TP
\fB\-e\fR, \fB\-\-exclude\fR
Excludes specific scripts [array]
.TP
\fB\-m\fR, \fB\-\-multiple\fR
Allows the selection of multiple items [boolean]
.TP
\fB\-s\fR, \fB\-\-size\fR
Amount of lines to display at once [number]
.TP
\fB\-\-rerun\-cache\-dir\fR
Defines the rerun task cache location [string]
.TP
\fB\-\-rerun\-cache\-name\fR
Defines the rerun task cache filename [string]
.TP
\fB\-\-no\-rerun\-cache\fR
Never write to or read from cache [boolean]
.TP
\fB\-v\fR, \fB\-\-version\fR
Show version number [boolean]
.TP
\fB\-r\fR, \fB\-\-rerun\fR
Rerun last executed script [boolean]
.PP
Visit https://github.com/ruyadorno/ntl for more info
.SH "SEE ALSO"
The full documentation for
.B ntl
is maintained as a Texinfo manual. If the
.B info
and
.B ntl
programs are properly installed at your site, the command
.IP
.B info ntl
.PP
should give you access to the complete manual.
.P
.P
Interactive cli tool that lists and run \fBpackage\.json\fP scripts\.
.QP
.P
An iPipeTo \fIhttps://github\.com/ruyadorno/ipt\fR workflow

.RE
.SH INSTALL
.P
.RS 2
.nf
npm install \-g ntl
.fi
.RE
.SH USAGE
.P
Navigate to any folder containing a \fBpackage\.json\fP file (usually a Node\.js project) that has configured \fBscripts\fR, then just use the ntl command:
.P
.RS 2
.nf
ntl
.fi
.RE
.P
You can also specify a path to a project folder containing a \fBpackage\.json\fP file:
.P
.RS 2
.nf
ntl \./my\-node\-project
.fi
.RE

.SH FEATURES
.RS 0
.IP \(bu 2
Interactive interface that lists all \fBpackage\.json\fP scripts
.IP \(bu 2
Select any item in the interactive interface to execute that task
.IP \(bu 2
Add descriptions to each task that can be shown in the UI
.IP \(bu 2
Multiple interactive interfaces (menu list, autocomplete fuzzy search)
.IP \(bu 2
Many options to customize the UI (exclude scripts, amount of items, etc)
.IP \(bu 2
Easy to repeat last ran script (\fBnt\fP and \fBrerun\fP options)
.IP \(bu 2
Run multiple tasks (can also easily repeat multiple ran tasks)
.IP \(bu 2
Customize rerun cache options

.RE
.SH CUSTOMIZE
.SS Custom runner
.P
By default \fBNode Task List\fR tries to use npm \fIhttps://github\.com/npm/cli/\fR to run the configured \fBscript\fP tasks\. In case you want to use a custom runner (e\.g: \fByarn\fP or \fBpnpm\fP) you can configure \fBntl\fR to use whatever runner you prefer\.
.P
That can be configured system\-wide by setting the environment variable in your profile file (\fB\|\.bashrc\fP or \fB\|\.bash_profile\fP for macos)\. In case you only want to ever use \fByarn\fR as your node task runner, you should set:
.P
.RS 2
.nf
# \.bashrc (linux) OR \.bash_profile (macos)
export NTL_RUNNER=yarn
.fi
.RE
.P
Keep in mind environment variables are flexible enough that they can also be set temporarily prior to running a command, so the following would also work:
.P
.RS 2
.nf
NTL_RUNNER=yarn ntl
.fi
.RE
.P
You can also define a \fBrunner\fP in a per\-project basis using the \fBntl\fP configuration of your \fBpackage\.json\fP, e\.g:
.P
.RS 2
.nf
{
"name": "<project>",
"version": "1\.0\.0",
"ntl": {
"runner": "yarn"
}
}
.fi
.RE
.SS Using task descriptions
.P
You can define descriptions for your tasks in your \fBpackage\.json\fP file by defining a \fBntl\fP section, e\.g:
.P
.RS 2
.nf
{
"name": "<project>",
"version": "1\.0\.0",
"scripts": {
"build": "make build",
"coverage": "jest \-\-coverage",
"test": "jest"
},
"ntl": {
"descriptions": {
"build": "Builds the project",
"coverage": "Run test outputing code coverage",
"test": "Run project's tests"
}
}
}
.fi
.RE
.P
These descriptions will be shown anytime you run \fBntl\fP\|\.
.SS Displaying task contents
.P
Use the \fB\-\-info\fP or simply \fB\-i\fP option in order to display the contents of each script task, like:
.P
.RS 2
.nf
ntl -i
.fi
.RE
.P
Task contents will also be shown when using the \fB\-\-descriptions\fP option and no description is available for a given item\.
.SS Exclude tasks from UI
.P
You can define a list of scripts to be excluded from the interactive menu using the \fB\-\-exclude\fP option:
.P
.RS 2
.nf
ntl \-e coverall tasks
.fi
.RE
.P
You can also use a wildcard character to exclude multiple scripts:
.P
.RS 2
.nf
ntl \-e "test*"
.fi
.RE
.SS Exclude tasks with missing descriptions
.P
You can also filter out items that doesn't have a description using the \fB\-\-descriptions\-only\fP or \fB\-o\fP option\.
.SS Customize cache
.P
\fBntl\fR uses a cache system that stores the last ran command for each project in order to make it easier for users to repeat it\. Given its importance, the following environment variables are available in order to customize its location and size:
.RS 0
.IP \(bu 2
\fBNTL_RERUN_CACHE_DIR\fP: Defines a directory to store the cache file
.IP \(bu 2
\fBNTL_RERUN_CACHE_NAME\fP: Filename to use for the cache
.IP \(bu 2
\fBNTL_RERUN_CACHE_MAX\fP: Number of items to store in the cache (defaults to \fB10\fP)
.IP \(bu 2
\fBNTL_NO_RERUN_CACHE\fP: When defined, avoid the cache system completely

.RE
.P
For example, if a given user wanted to store its cache in \fB~/\.ntl/cache\fP location and save up to 100 items in it, they could add the following to their \fB\|\.bashrc\fP (linux) or \fB\|\.bash_profile\fP (macos):
.P
.RS 2
.nf
export NTL_RERUN_CACHE_DIR=$HOME
export NTL_RERUN_CACHE_NAME=cache
export NTL_RERUN_CACHE_MAX=100
.fi
.RE
.P
The cache can also be customized through command line options:
.RS 0
.IP \(bu 2
\fB\-\-rerun\-cache\-dir\fP Defines a directory to store the cache file
.IP \(bu 2
\fB\-\-rerun\-cache\-name\fP: Filename to use for the cache
.IP \(bu 2
\fB\-\-no\-rerun\-cache\fP: Avoids the cache system completely

.RE
.SS UI Size
.P
You can increase/reduce the size of the presented UI list using the \fB\-\-size\fP or \fB\-s\fP option\. In this example we just increased the size of the list to show up to 12 items at once:
.P
.RS 2
.nf
ntl \-s 12
.fi
.RE
.P
The default size value is 7 items\.
.SH REPEAT THE LAST RAN TASK
.P
\fBntl\fR provides many options to make it easier to rerun the last task, either through having it selected as default option the next time you run the \fBntl\fP command, or by using one of the following:
.RS 0
.IP \(bu 2
\fBThe ultra convenient way\fR: \fBnt\fP command shorthand (You should think of \fBnt\fP as: "ok, just run the last node task", in contrast to \fBntl\fP which should be interpreted as: "ok, give me the node task list again") in case no previous task is available, running \fBnt\fP will behave exactly as \fBntl\fP
.IP \(bu 2
Using a \fB\-\-rerun\fP or \fB\-r\fP flag, e\.g: \fBntl \-r\fP
.IP \(bu 2
Prepending the \fBNTL_RERUN\fP env variable, e\.g: \fBNTL_RERUN=true ntl\fP

.RE

.SH RUN MULTIPLE TASKS
.P
Using the \fB\-\-multiple\fP or \fB\-m\fP option, the interface becomes a checkbox\-based list that allows you to select multiple tasks and run them in serial\.
.P
.RS 2
.nf
ntl \-m
.fi
.RE

.P
Better yet, combine that with the \fBrerun\fR feature and you can repeat multiple tasks using the \fBnt\fP command\.
.SH RUN IN AUTOCOMPLETE OR FUZZY SEARCH MODE
.P
Use \fB\-\-autocomplete\fP or \fB\-A\fP option in order to use an interface variation that allows you to type the name of the task instead of browsing through an arrow\-based menu\. This mode can be very helpful when managing a long list of tasks\.
.P
.RS 2
.nf
ntl \-A
.fi
.RE

.SH TIPS
.SS ntl as default task
.P
You can define \fBntl\fP as a dev dependency and one of the tasks of your project, specially \fBstart\fP \- so whenever someone runs \fBnpm start\fP or \fByarn start\fP they get the convenient \fBntl\fR interface\. Like in the following \fBpackage\.json\fP example:
.P
.RS 2
.nf
{
"name": "<project>",
"version": "1\.0\.0",
"scripts": {
"start": "ntl"
},
"devDependencies": {
"ntl": "^5\.0\.0"
}
}
.fi
.RE
.SS Exclude scripts
.P
You can also define a task that invokes \fBntl\fP while excluding other tasks, e\.g:
.P
.RS 2
.nf
{
"scripts": {
"test": "jest \-\-coverage",
"test:watch": "jest \-\-coverage \-\-watchAll",
"coveralls": "jest \-\-coverage \-\-coverageReporters=text\-lcov | coveralls",
"tasks": "ntl \-\-exclude coverall tasks"
}
}
.fi
.RE
.SS Included command aliases
.RS 0
.IP \(bu 2
\fBntl\fP The default command
.IP \(bu 2
\fBnodetasklist\fP Longhand version in case users have conflicting \fBntl\fP commands
.IP \(bu 2
\fBnpm\-tasklist\fP Legacy longhand version
.IP \(bu 2
\fBnt\fP Rerun last script shortcut
.IP \(bu 2
\fBnodetask\fP Rerun last script longhand

.RE
.SH HELP
.P
Still feel like you could use some \fB\-\-help\fP ?
.P
.RS 2
.nf
Usage:
ntl [<path>] Build an interactive interface and run any script
nt [<path>] Rerun last executed script

Options:
\-a, \-\-all Includes pre and post scripts on the list [boolean]
\-A, \-\-autocomplete Starts in autocomplete mode [boolean]
\-D, \-\-debug Prints to stderr any internal error [boolean]
\-d, \-\-descriptions Displays the descriptions of each script [boolean]
\-o, \-\-descriptions\-only Limits output to scripts with a description [boolean]
\-h, \-\-help Shows this help message [boolean]
\-i, \-\-info Displays the contents of each script [boolean]
\-e, \-\-exclude Excludes specific scripts [array]
\-m, \-\-multiple Allows the selection of multiple items [boolean]
\-s, \-\-size Amount of lines to display at once [number]
\-\-rerun\-cache\-dir Defines the rerun task cache location [string]
\-\-rerun\-cache\-name Defines the rerun task cache filename [string]
\-\-no\-rerun\-cache Never write to or read from cache [boolean]
\-v, \-\-version Show version number [boolean]
\-r, \-\-rerun Rerun last executed script [boolean]

Visit https://github\.com/ruyadorno/ntl for more info
.fi
.RE
.SH LICENSE
.P
MIT \fILICENSE\fR © 2019 Ruy Adorno \fIhttp://ruyadorno\.com\fR

0 comments on commit 58d59c4

Please sign in to comment.