Help defined in a section not working

[ianepperson]

I'm new to poe (thanks for this nice tool!) and it seems that defining the help text within a pyproject.toml section isn't working.

> poe --version
Poe the poet - version: 0.18.1

I think I have my pyproject.toml set up correctly:

[tool.poe.tasks]
test = {cmd="pytest", help="Run all tests"}
run = {cmd="./manage.py runserver", help="Run the server locally"}

[[tool.poe.tasks.shell]]
cmd = "./manage.py shell_plus"
help = "Run the Django console - THIS DOESN'T DISPLAY"

[[tool.poe.tasks.prod_shell]]
cmd = "./manage.py shell_plus"
help = "Run the Django console for prod - NOR THIS"
env = { ENVIRONMENT = "prod" }

However, for the shell tasks there's no help text:

> poe -h
Poe the Poet - A task runner that works well with poetry.
version 0.18.1

USAGE
  poe [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi] task [task arguments]

GLOBAL OPTIONS
  -h, --help     Show this help page and exit
  --version      Print the version and exit
  -v, --verbose  Increase command output (repeatable)
  -q, --quiet    Decrease command output (repeatable)
  -d, --dry-run  Print the task contents but don't actually run it
  --root PATH    Specify where to find the pyproject.toml
  --ansi         Force enable ANSI output
  --no-ansi      Force disable ANSI output

CONFIGURED TASKS
  test           Run all tests
  run            Run the server locally
  shell
  prod_shell

[nat-n]

Hi @ianepperson, thanks for the feedback :)

I think there's a subtle issue with your toml syntax in that you're using double square brackets around the lines with the task names. If you use single brackets instead then I think it should work as you expect.

What's happening here is that instead of defining a toml table for [tool.poe.tasks.shell], you're defining an array of tables which poe interprets as a sequence task with a single item, and in sequence tasks the subtask don't get help text (only the sequence task itself).

I'll take a note of this that it would probably be helpful if poe gave a validation error in this case, because the help option for tasks defined inside a sequence is not essentially ignored.

[ianepperson]

Thanks Nat! I updated my pyproject.toml and it now works as expected. I read through the TOML tables syntax and it helped me see the error of my ways! I think having that link near the top of your documentation would make things smoother for us new users - I didn't understand the complexities of TOML and the shifting syntax in your examples was a touch frustrating. Now it's clear.