diff --git a/doc/content/introduction.md b/doc/content/introduction.md index 62c5a5f..302dfa3 100644 --- a/doc/content/introduction.md +++ b/doc/content/introduction.md @@ -1,6 +1,6 @@ --- linkTitle: Introduction -title: xc - Simple, Convenient, Markdown based task runner. +title: xc - Simple, Convenient, Markdown based task runner. type: homepage date: 2022-03-19:15:00+00:00 --- diff --git a/doc/content/task-syntax/command.md b/doc/content/task-syntax/command.md index e0dc824..376a0ad 100644 --- a/doc/content/task-syntax/command.md +++ b/doc/content/task-syntax/command.md @@ -5,4 +5,20 @@ linkTitle: "Task Command" menu: { main: { parent: 'task-syntax', weight: 10 } } --- -TODO: Document command syntax +## How to define a command to run a task + +The command of a task is what will be executed through the command line when the task is run. + +To define a command you must add a code block under a particular task. + +````markdown +## Tasks +### Task1 +``` +echo "Hello 世界!" +echo "Hello العالمية!" +echo "Hello ертөнц!" +``` +```` + +Everything inside the code block will be run on the command line as if it is a shell script. \ No newline at end of file diff --git a/doc/content/task-syntax/dependancies.md b/doc/content/task-syntax/dependancies.md deleted file mode 100644 index 04f660d..0000000 --- a/doc/content/task-syntax/dependancies.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Dependancies" -description: -linkTitle: "Dependancies" -menu: { main: { parent: 'task-syntax', weight: 10 } } ---- - -TODO: Document Dependancies keyword diff --git a/doc/content/task-syntax/dependencies.md b/doc/content/task-syntax/dependencies.md new file mode 100644 index 0000000..a78ad45 --- /dev/null +++ b/doc/content/task-syntax/dependencies.md @@ -0,0 +1,72 @@ +--- +title: "Dependencies" +description: +linkTitle: "Dependencies" +menu: { main: { parent: 'task-syntax', weight: 10 } } +--- + +## How to create a dependency between two tasks + +You can run another before the task you're trying to run as a dependency. + +For example, you want to run a task to deploy your code, but you want to run all the unit tests and linters before that happens. + +Before the command section of the task, you may define comma seperated dependencies with `requires:` or `req:` followed by the name of the tasks that are dependencies. + +````markdown +## Tasks + +### Test +``` +sh test.sh +``` + +### Lint +``` +sh lint.sh +``` + +### Deploy +requires: Test, Lint +``` +sh deploy.sh +``` +```` + +## Chaining tasks with dependencies + +You can chain tasks through the use of dependencies. + +````markdown +## Tasks + +### Task1 +``` +echo "TASK 1" +``` + +### Task2 +requires: Task1 +``` +echo "TASK 2" +``` + +### Task3 +requires: Task2 +``` +echo "TASK 3" +``` +```` + +Running `xc Task3` will yield: + +``` +echo "TASK 1" +TASK 1 +echo "TASK 2" +TASK 2 +echo "TASK 3" +TASK 3 +``` + +Running in the order of `Task1` -> `Task2` -> `Task` \ No newline at end of file diff --git a/doc/content/task-syntax/directory.md b/doc/content/task-syntax/directory.md index 367258b..aa0f289 100644 --- a/doc/content/task-syntax/directory.md +++ b/doc/content/task-syntax/directory.md @@ -5,4 +5,17 @@ linkTitle: "Directory" menu: { main: { parent: 'task-syntax', weight: 10 } } --- -TODO: Document Directory keyword +## How to use a custom working directory + +You can define the working directory of the task for the command to run in. + +Do this by adding a `dir:` or `directory:` between the H3 of the task name and the command. + +````markdown +## Tasks +### Build +directory: ./src +``` +sh build.sh +``` +```` \ No newline at end of file diff --git a/doc/content/task-syntax/environment-variables.md b/doc/content/task-syntax/environment-variables.md index b9f0557..455cc02 100644 --- a/doc/content/task-syntax/environment-variables.md +++ b/doc/content/task-syntax/environment-variables.md @@ -4,5 +4,44 @@ description: linkTitle: "Environment Variables" menu: { main: { parent: 'task-syntax', weight: 10 } } --- +## How to use environment variables -TODO: Document Env +You can define environment variables that will be used during the execution of your task. + +Do this by adding an `env:` or `environment:` between the H3 of the task name and the command + +````markdown +## Tasks +### Task1 +Env: ENVIRONMENT=PRODUCTION +``` +echo $ENVIRONMENT +``` +```` + +## Multiple environment variables + +You can define multiple environment variables. + +````markdown +## Tasks +### Task1 +Env: ENVIRONMENT=PRODUCTION +Env: VERSION=1.2 +``` +echo $ENVIRONMENT +echo $VERSION +``` +```` + +or + +````markdown +## Tasks +### Task1 +Env: ENVIRONMENT=PRODUCTION, VERSION=1.2 +``` +echo $ENVIRONMENT +echo $VERSION +``` +```` \ No newline at end of file diff --git a/doc/content/task-syntax/index.md b/doc/content/task-syntax/index.md index 36a8c60..1ff8815 100644 --- a/doc/content/task-syntax/index.md +++ b/doc/content/task-syntax/index.md @@ -1,12 +1,21 @@ --- title: "Task Syntax" weight: 1 -description: Task Syntax +description: linkTitle: "Task Syntax" --- ## The anatomy of an `xc` task. +### Structure + +- Tasks Section + - Task Name + - Dependencies + - Directory + - Environment Variables + - Command + ### Example ````md diff --git a/doc/content/task-syntax/task-name.md b/doc/content/task-syntax/task-name.md index 6e2c586..5ae0b13 100644 --- a/doc/content/task-syntax/task-name.md +++ b/doc/content/task-syntax/task-name.md @@ -5,4 +5,30 @@ linkTitle: "Name" menu: { main: { parent: 'task-syntax', weight: 2 } } --- -TODO: Document names +## How to define a task + +Under the `## Tasks` heading, you may define as many tasks as you'd like. Each task is defined with a name by adding a H3 heading like `### TaskName` + +```markdown +## Tasks + +### Task1 + +### Task2 + +### Task3 +``` + +## Constraints + +You cannot use spaces in the task name. + +But you may use `-` or `_` + +```markdown +## Tasks + +### Task_1 + +### Task-2 +``` \ No newline at end of file diff --git a/doc/content/task-syntax/tasks-section.md b/doc/content/task-syntax/tasks-section.md index 6bb70da..697309c 100644 --- a/doc/content/task-syntax/tasks-section.md +++ b/doc/content/task-syntax/tasks-section.md @@ -5,4 +5,38 @@ linkTitle: "Tasks Section" menu: { main: { parent: 'task-syntax', weight: 1 } } --- -TODO: Tasks section +## Tasks Section + +An xc compatible markdown file needs to define a heading of any level called `Tasks`. + +The tasks within a `Tasks` section will need to be one heading level lower than `Tasks`. + +```markdown +## Tasks + +### Task1 + +### Task2 + +## Next H2 Heading +``` + +Between `## Tasks` and `## Next H2 Heading` you can define your tasks. + +or + +```markdown +# Tasks + +## Task1 + +## Task2 + +# Next H1 Heading +``` + +Please note that the word `tasks` is not case sensitive. + +## Constraints + +You cannot define two `Tasks` sections. If you do, the one that appears first in the markdown file will be used \ No newline at end of file