Skip to content

Commit 8ee47d5

Browse files
Fix maintainers/contributors TOC links (#42)
1 parent 9e8d522 commit 8ee47d5

File tree

1 file changed

+62
-17
lines changed

1 file changed

+62
-17
lines changed

README.md

Lines changed: 62 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,30 @@
11
<p align="center">
2-
3-
<img src="https://github.com/illBeRoy/taskipy/raw/master/logo.svg" width="150" />
4-
2+
<img src="./logo.svg" width="150" />
53
</p>
64

75
- [General](#general)
86
- [Requirements](#requirements)
97
- [Usage](#usage)
10-
* [Installation](#installation)
11-
* [Adding Tasks](#adding-tasks)
12-
* [Running Tasks](#running-tasks)
13-
* [Passing Command Line Args to Tasks](#passing-command-line-args-to-tasks)
14-
* [Composing Tasks](#composing-tasks)
15-
* [Using Variables](#using-variables)
16-
* [Using Taskipy Without Poetry](#using-taskipy-without-poetry)
17-
* [Advanced Use Cases](#advanced-use-cases)
18-
- [Maintainers 🚧](#maintainers---)
19-
- [Contributors ✨](#contributors--)
8+
- [Installation](#installation)
9+
- [Adding Tasks](#adding-tasks)
10+
- [Running Tasks](#running-tasks)
11+
- [Passing Command Line Args to Tasks](#passing-command-line-args-to-tasks)
12+
- [Composing Tasks](#composing-tasks)
13+
- [Grouping Subtasks Together](#grouping-subtasks-together)
14+
- [Pre Task Hook](#pre-task-hook)
15+
- [Post Task Hook](#post-task-hook)
16+
- [Using Variables](#using-variables)
17+
- [String Formatting](#string-formatting)
18+
- [Always Use Variables](#always-use-variables)
19+
- [Using Taskipy Without Poetry](#using-taskipy-without-poetry)
20+
- [Installing With PIP](#installing-with-pip)
21+
- [Running Tasks](#running-tasks-1)
22+
- [Advanced Use Cases](#advanced-use-cases)
23+
- [Maintainers :construction:](#maintainers-construction)
24+
- [Contributors :sparkles:](#contributors-sparkles)
2025

2126
## General
27+
2228
[![pypi](https://img.shields.io/pypi/v/taskipy?style=flat-square)](https://pypi.org/project/taskipy/)
2329
[![pypi-downloads](https://img.shields.io/pypi/dm/taskipy?style=flat-square)](https://pypi.org/project/taskipy/)
2430
[![ci](https://img.shields.io/github/workflow/status/illberoy/taskipy/Taskipy%20Test%20CI?style=flat-square)](https://github.com/illBeRoy/taskipy/actions?query=workflow%3A%22Taskipy+Test+CI%22)
@@ -29,16 +35,19 @@
2935
Every development pipeline has tasks, such as `test`, `lint` or `publish`. With taskipy, you can define those tasks in one file and run them with a simple command.
3036

3137
For instance, instead of running the following command:
38+
3239
```bash
3340
python -m unittest tests/test_*.py
3441
```
3542

3643
You can create a task called `test` and simply run:
44+
3745
```bash
3846
poetry run task test
3947
```
4048

4149
Or (if you're not using poetry):
50+
4251
```bash
4352
task test
4453
```
@@ -48,25 +57,31 @@ In addition, you can compose tasks and group them together, and also create depe
4857
This project is heavily inspired by npm's [run script command](https://docs.npmjs.com/cli/run-script).
4958

5059
## Requirements
60+
5161
Python 3.6 or newer.
5262

5363
Your project directory should include a valid `pyproject.toml` file, as specified in [PEP-518](https://www.python.org/dev/peps/pep-0518/).
5464

5565
## Usage
66+
5667
### Installation
68+
5769
To install taskipy as a dev dependency, simply run:
70+
5871
```bash
5972
poetry add --dev taskipy
6073
```
6174

62-
### Adding Tasks
75+
### Adding Tasks
76+
6377
In your `pyproject.toml` file, add a new section called `[tool.taskipy.tasks]`.
6478

6579
The section is a key-value map, from the names of the task to the actual command that should be run in the shell.
6680

6781
There are two ways to define tasks. The easy way is to simply write the command down as a string:
6882

6983
__pyproject.toml__
84+
7085
```toml
7186
[tool.taskipy.tasks]
7287
test = "python -m unittest tests/test_*.py"
@@ -76,6 +91,7 @@ lint = "pylint tests taskipy"
7691
Alternatively, you can define tasks more explicitly by declaring both the command and a helpful description using an inline table:
7792

7893
__pyproject.toml__
94+
7995
```toml
8096
[tool.taskipy.tasks]
8197
test = { cmd = "python -m unittest tests/test_*.py", help = "runs all unit tests" }
@@ -85,34 +101,41 @@ lint = { cmd = "pylint tests taskipy", help = "confirms code style using pylint"
85101
The explicit notation is more verbose, but provides better context to anyone who uses the task.
86102

87103
### Running Tasks
104+
88105
In order to run a task, run the following command in your terminal:
106+
89107
```bash
90108
$ poetry run task test
91109
```
92110

93111
You can also list all existing tasks by running the following:
112+
94113
```bash
95114
$ poetry run task --list
96115
test python -m unittest tests/test_*.py
97116
lint pylint tests taskipy
98117
```
99118

100119
If you declared your task explicitly, you will see the description of the task by the side of the task's name:
120+
101121
```bash
102122
$ poetry run task --list
103123
test runs all unit tests
104124
lint confirms code style using pylint
105125
```
106126

107127
### Passing Command Line Args to Tasks
128+
108129
If you want to pass command line arguments to tasks (positional or named), simply append them to the end of the task command.
109130

110131
For example, running the above task like this:
132+
111133
```bash
112134
poetry run task test -h
113135
```
114136

115137
Is equivalent to running:
138+
116139
```bash
117140
python -m unittest tests/test_*.py -h
118141
```
@@ -122,15 +145,19 @@ And will show unittest's help instead of actually running it.
122145
> ⚠️ Note: if you are using pre \ post hooks, do notice that arguments are not passed to them, only to the task itself.
123146
124147
### Composing Tasks
148+
125149
#### Grouping Subtasks Together
150+
126151
Some tasks are composed of multiple subtasks. Instead of writing plain shell commands and stringing them together, you can break them down into multiple subtasks:
152+
127153
```toml
128154
[tool.taskipy.tasks]
129155
lint_pylint = "pylint tests taskipy"
130156
lint_mypy = "mypy tests taskipy"
131157
```
132158

133159
And then create a composite task:
160+
134161
```toml
135162
[tool.taskipy.tasks]
136163
lint = "task lint_pylint && task lint_mypy"
@@ -139,14 +166,17 @@ lint_mypy = "mypy tests taskipy"
139166
```
140167

141168
#### Pre Task Hook
169+
142170
Tasks might also depend on one another. For example, tests might require some binaries to be built. Take the two following commands, for instance:
171+
143172
```toml
144173
[tool.taskipy.tasks]
145174
test = "python -m unittest tests/test_*.py"
146175
build = "make ."
147176
```
148177

149178
You could make tests depend on building, by using the **pretask hook**:
179+
150180
```toml
151181
[tool.taskipy.tasks]
152182
pre_test = "task build"
@@ -157,14 +187,17 @@ build = "make ."
157187
The pretask hook looks for `pre_<task_name>` task for a given `task_name`. It will run it before running the task itself. If the pretask fails, then taskipy will exit without running the task itself.
158188

159189
#### Post Task Hook
190+
160191
From time to time, you might want to run a task in conjuction with another. For example, you might want to run linting after a successful test run. Take the two following commands, for instance:
192+
161193
```toml
162194
[tool.taskipy.tasks]
163195
test = "python -m unittest tests/test_*.py"
164196
lint = "pylint tests taskipy"
165197
```
166198

167199
You could make tests trigger linting, by using the **posttask hook**:
200+
168201
```toml
169202
[tool.taskipy.tasks]
170203
test = "python -m unittest tests/test_*.py"
@@ -175,6 +208,7 @@ lint = "pylint tests taskipy"
175208
The posttask hook looks for `post_<task_name>` task for a given `task_name`. It will run it after running the task itself. If the task failed, then taskipy will not run the posttask hook.
176209

177210
### Using Variables
211+
178212
In some cases, you might find yourself passing the same arguments over and over again. Let us take a look at the following tasks:
179213

180214
```toml
@@ -197,14 +231,17 @@ black = { cmd = "pylint {path}", use_vars = true }
197231
```
198232

199233
We have made the following changes to our configuration:
234+
200235
1. We declared variables under `tool.taskipy.variables`
201236
2. We flagged the relevant task using `use_vars` to note that they should use the variables
202237
3. We replaced the repeating path with a `{path}` variable
203238

204239
#### String Formatting
240+
205241
The formatting of the task commands uses python's own `string.format` method, and therefore supports everything that python's [formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals) let you do.
206242

207243
#### Always Use Variables
244+
208245
Using variables is opt-in, which means that by default commands do **not** use them, and you will have to turn them on a task to task basis.
209246

210247
If you want to turn on `use_vars` globally, all you need to do is to declare that under taskipy's **settings** table:
@@ -222,33 +259,40 @@ black = "black {path}"
222259
```
223260

224261
### Using Taskipy Without Poetry
262+
225263
Taskipy was created with poetry projects in mind, but actually only requires a valid `pyproject.toml` file in your project's directory. As a result, you can use it even eithout poetry:
226264

227265
#### Installing With PIP
266+
228267
Install taskipy on your machine or in your virtualenv using:
268+
229269
```bash
230270
pip install taskipy
231271
```
232272

233273
#### Running Tasks
274+
234275
Head into your project's directory (don't forget to activate virtualenv if you're using one), and run the following command:
276+
235277
```bash
236278
task TASK
237279
```
280+
238281
Where `TASK` is the name of your task.
239282

240283
### Advanced Use Cases
284+
241285
If you have a more specific use case, you might not be the first to run into it! Head over to the [ADVANCED_FEATURES](./docs/ADVANCED_FEATURES.md) doc, and look it up.
242286

243-
## Maintainers 🚧
287+
## Maintainers :construction:
244288

245289
<table>
246290
<tr>
247291
<td align="center"><a href="https://github.com/illBeRoy"><img src="https://avatars2.githubusercontent.com/u/6681893?v=4" width="100px;" alt=""/><br /><sub><b>Roy Sommer</b></sub></a></td>
248292
</tr>
249293
</table>
250294

251-
## Contributors
295+
## Contributors :sparkles:
252296

253297
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
254298

@@ -267,4 +311,5 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
267311
<!-- prettier-ignore-end -->
268312
<!-- ALL-CONTRIBUTORS-LIST:END -->
269313

270-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
314+
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
315+
specification. Contributions of any kind welcome!

0 commit comments

Comments
 (0)