Task Runner
Run build tasks
Runs named task functions that return streams, arrays of deferred task functions or invoke the callback function.
Install
Install the mkdoc tools for the mk
program:
npm i -g mkdoc
Usage
Create a mkdoc.js
task file like this one (source file):
var mk = ; // @task readme build the readme file. { mk // read markdown source document // parse processing instructions // include link references // make links absolute // append generator message // inject table of contents list // convert abstract syntax tree to markdown // write the result to a file ; // proceed to next task} mk;
Note that you should not install the mktask
dependency, it is resolved by the command line program.
Example
Build all tasks (or a main task when defined):
mk
Build specific tasks:
mk api readme
Use a specific build file:
mk -f ~/mkdoc.js readme
To see a list of tasks use:
mk --tasks
Guide
This guides assumes you are using the mk
program to run tasks, install it with npm i -g mkdoc
.
Creating Tasks
Tasks are named functions that are passed to the task
function:
var mk = ; // @task readme build the readme file. { // implement task logic ;} mk;
Anonymous functions are not allowed and will generate an error if used.
Task Documentation
It is considered good practice to annotate your tasks with comments that provide a name and description of the task so that it will be included in the list printed when running mk --tasks
.
// @task readme build the readme file.
Task Names
By default the task identifier (referenced on the command line) is taken from the function name but you may explicitly specify an identifier if you prefer:
mk;
If you have dependencies the identifier comes afterwards:
mk;
When multiple tasks are passed then the identifier is taken from the last function which in this case becomes readme
:
mk;
Main Task
The mk
program when executed with no arguments will either run all available tasks in series or a main
task if declared. To declare a main task give it the name main
:
var mk = ; // @task main build all documentation. { // implement task logic ;} mk;
Deferred Tasks
Typically task functions will invoke the callback function when done but they may also return an array of task functions which is useful when a task wishes to defer to a series of other tasks:
var mk = ; // @task api build the api docs. { // implement api task logic ;} // @task readme build the readme file. { // implement readme task logic ;} // @task main build the api and readme docs. { return api readme;} mk;mk;mk;
Note that when deferring to other task functions they must have been registered by calling task()
.
Stream Tasks
Sometimes when creating complex stream pipelines it is useful to return streams so that parts of the pipeline become reusable between tasks, for example:
var mk = ast = ; { return mk ;} { return mk;} mk;
When a task returns a stream it is piped to the next task function in the pipeline and the callback function is added as a listener for the finish
event on the last stream in the pipeline.
Task Dependencies
Task functions may declare an array of functions to call before the task function(s).
Dependencies are executed in parallel but they must all complete before the tasks are executed:
var mk = ; // @task api build the api docs.
Task Arguments
Task functions are automatically exposed the parsed arguments object via this.args
such that mk readme --env devel
would result in the readme task being able to access the env
option using this.args.options.env
.
Flags are available in this.args.flags
such that mk readme -v
yields true
for this.args.flags.v
.
Note that some command line arguments are handled by the mk
program you should take care that the names do not conflict.
For detailed information on the args
object see the argparse library.
Sample
Inline code examples from the working example in /doc/example.
The build file mkdoc.js:
var mk = ; // @task example build the example file. { mk // read markdown source document // parse processing instructions // include link references // convert abstract syntax tree to markdown // print the result ; // proceed to next task} mk;
The input source file source.md:
# Source Example for the mk(1) program supplied by [mkdoc][]. A paragraph of markdown text followed by an include processing instruction. <? @include include.md ?> Followed by some more markdown content and the result of executing a shell command: <? @exec uname ?> Finally include the link definition file. <? @include links.md ?>
Include file include.md:
## Include A file that was included from another markdown document.
Include file links.md:
[mkdoc]: https://github.com/mkdoc/mkdoc
Result:
# Source Example for the mk(1) program supplied by [mkdoc][]. A paragraph of markdown text followed by an include processing instruction. ## Include A file that was included from another markdown document. Followed by some more markdown content and the result of executing a shell command: Linux Finally include the link definition file. [mkdoc]: https://github.com/mkdoc/mkdoc
Help
Usage: mk [-h] [--tasks] [--help] [--version] [--file=<file...>] [task...]
Task runner.
Options
-f, --file=[FILE...] Load specific task files
--tasks Print task list
-h, --help Display help and exit
--version Print the version and exit
mktask@1.3.10
API
mk
Creates a task collection.
Returns a Task.
#task
static
Adds a task to the default task collection.
Returns a Task.
Task
Encapsulates a collection of named task functions.
.task
Taskprototype
Adds task function(s) to the list of known tasks.
.get
Taskprototype
Get a task map by function reference.
Returns a task map if found.
.run
Taskprototype
Gets a task runner for this collection of tasks.
Returns a task Runner.
#src
static
Parses a markdown string into a stream.
Returns the output stream.
#dest
static
Get a destination output stream.
If the file option is not given a destination stream that prints to stdout is returned.
Returns an output stream.
file
String path to the output file.
runner
Get a task runner.
Returns a Runner.
opts
Object processing options.
Runner
opts
Execute task functions.
opts
Object processing options.
Options
task
Object collection of tasks.
.get
Runnerprototype
Get a task by name identifier.
Returns a task or undefined.
id
Function|String task identifier.
.series
Runnerprototype
Execute task functions in series.
list
Array of task functions.cb
Function callback function.
.parallel
Runnerprototype
Execute task functions in parallel.
list
Array of task functions.concurrent
Number number of concurrent calls.cb
Function callback function.
.resolve
Runnerprototype
Resolves dependencies for a task.
Searches for dependencies that are tasks and injects any dependencies for located tasks.
Returns an array of task dependencies.
cb
Function callback function.
.exec
Runnerprototype
Execute a task by name identifier.
Dependencies are run in parallel before task execution.
Returns a task or undefined.
id
Function|String task identifier.cb
Function callback function.
.each
Runnerprototype
Execute a list of tasks.
When names
is not given and no main task exists all tasks are executed;
if a main task exists it is executed.
names
Array list of task identifiers or task functions.cb
Function callback function.
License
MIT
Created by mkdoc on May 22, 2016