Improve Documentation about Collections /tasks directories
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Start with the existing “Collection-based configuration” section and the tasks/init.py and tasks/example.py layout described in the report. Define what a Collection is, explain how to build a tasks directory hierarchy and its loading behavior, and expand getting started with ordered steps and a working example. Done means a newcomer can create the example and understand why invoke -l finds its task.
Written by the indexing model from the issue text.
Description
Hi,
I have a long background from traditional make and Ruby's rake, but need to migrate some tasks to a system which has python3 only, and thus I'm currently learning invoke.
After I read somewhere that invoke can read the tasks not only from a single tasks.py, but a tasks directory with a hierarchy of files, but invoke's own documentation is not really informative about that. It was quite difficult to find that these are called "Collections", and that invoke prefers a tasks directory over a tasks.py due to python's loading mechanism.
However, I created a tasks with a tasks/init.py and a tasks/example.py, but the task in example.py is not found by invoke -l and I don't see why.
Sorry to say, but your documentation does not really help and is rather incomprehensible. In other words: If one has the knowledge required to understand your documentation, he doesn't need it anymore.
A documentation should consist of a systematical order of steps, each explaining how to use the tool, and in fact, there is a "getting started", but this stops after the very basics.
There is a documents section 3.1.6 Collection-based configuration , but it doesn't even bother to define the term or tell what the term "Collection" means here, or what it looks like. One can read it and read it and read it and still doesn't know what it is or how to build one.
regards
- Dominant language
- Python
- Stars
- 4.8k
- Forks
- 412
- PR merge metrics
- No merged PRs in 30d
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from pyinvoke/invoke
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Similar issues
-
documentation help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
simonw/sqlite-utils#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100