Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Revert -docs back to table format and add -longdocs #66

Closed
bladeoflight16 opened this Issue · 6 comments

3 participants

@bladeoflight16

The -docs parameter is designed to be a handy reference list of the available tasks. I work on a team of usually 2 to 5 people, and usually several team members know very little about the build scripts. Sometimes they ask me what commands to use, and I often tell them to use -docs to check because I don't always remember off-hand myself. Now, my scripts often have 10 or more tasks. This is easy to reach since they deal with configuration, compilation, database deployment, unit/integration tests, packaging, and even deployment to dev sites. Imagine me telling a UI developer to look at -docs and this is what he gets: (You can just scroll past without reading.)

Name        : Task0
Alias       :
Description :
Depends On  :
Default     :

Name        : Task1
Alias       :
Description :
Depends On  :
Default     :

Name        : Task2
Alias       :
Description :
Depends On  :
Default     :

Name        : Task3
Alias       :
Description :
Depends On  :
Default     :

Name        : Task4
Alias       :
Description :
Depends On  :
Default     :

Name        : Task5
Alias       :
Description :
Depends On  :
Default     :

Name        : Task6
Alias       :
Description :
Depends On  :
Default     :

Name        : Task7
Alias       :
Description :
Depends On  :
Default     :

Name        : Task8
Alias       :
Description :
Depends On  :
Default     :

Name        : Task9
Alias       :
Description :
Depends On  :
Default     :

I hope this simple example is enough to prove that the current implementation of -docs makes it utterly useless as a quick reference. That's only 10 tasks. Only the smallest of build scripts are going to have less than 5.

For this reason, I would like to propose two changes:

  1. Change -docs back to its original behavior of printing a compact table.
  2. Add a -longdocs parameter that prints out a long list like above. This would be allowed to appear with or without the -docs parameter.

I considered leaving -docs with its current functionality and adding something to give a table, but I decided to propose this instead because a second -docs-like parameter is more likely to be discovered by power users, which the long list is aimed at. I think it makes more sense for -docs to be the common users' implementation and for a second parameter to be geared towards power users.

I'm willing to work on this myself, but I'd like to get the requirements straight first. How does this proposal sound? Are there better ways of doing this?

@damianh damianh added the UpForGrabs label
@damianh
Owner

I like this proposal. Please send a PR, thx.

@lholman

@damianh, seeing as it's been 10 months I'd be happy to submit a PR for this one up if @bladeoflight16 isn't available to do it now?

@damianh
Owner

@lholman make it so. I'll create a temporary package on myget. I'll need you to test it before I push it to nuget etc. Can you do that?

@lholman

@damianh Of course, I'll send over a PR in the next few days on a different branch and you can tell me what you need from there.

@bladeoflight16

Sorry for being unresponsive. I've been very busy lately, even though I saw the request for a PR. @lholman I would be extremely grateful if you have the time. =) I'm not exactly sure when I'd be able to get around to it with 3 projects at work all trying to have releases end of April/early May.

@lholman lholman referenced this issue from a commit in lholman/psake
@lholman lholman #66 - Revert -docs back to table format and add -longdocs
- It turns out the previous -docs implementation was reverted some months ago in the following commit psake@b1d8518 to use the original and more compact format-table for output, this is part of the most recent release (v4.3.2).
- This commit adds the -detailedDocs parameter to use format-list for more detailed and list formatted documentation.
c4a3359
@damianh
Owner

Fixed via #109

@damianh damianh closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.