614130 - distinguish between supported/experimental/internal commands/options and tool/command options

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect)

Description

[Myk Melez [:myk] [@mykmelez]]

The cfx --help output should distinguish between supported, experimental, and internal commands and options, noting that the experimental and internal commands/options might be changed or removed in the future.

It should also distinguish between options for the cfx tool itself (or all commands generally) and those for individual commands (or subsets thereof), with the former being specifiable only before the command argument, and the latter being specifiable only after it.

(Note: actually enforcing those requirements is non-trivial, but for the purposes of shipping a beta, it is only necessary to make the documentation differentiate between the kinds of options and specify which kind must go where, since the implementation is more lenient than the proposed documentation, and thus we can update the implementation to match the documentation at a later date without breaking documentation-based expectations.)

Finally, it should identify the command argument as a required argument to the tool (currently it identifies it as optional).

Internal Commands and Options:
  commands: sdocs, test* (but not "test")
  options: --e10s, --keydir, --addons, --test-runner-pkg

Experimental Commands and Options:
  commands: develop
  options: --use-server

cfx Tool and General Options:

  -h, --help
  -v, --verbose

Command-specific Options:

  Supported Commands:
    docs

    init

    test
      -g, --use-config
      -a, --app
      -b, --binary
      -p, --profiledir
      --dependencies
      -f, --filter
      --times

      Internal Options:
        --addons
        --keydir
        --test-runner-pkg
        --e10s

    run
      -g, --use-config
      --static-args
      --pkgdir
      --extra-packages
      --templatedir
      -a, --app
      -b, --binary
      -p, --profiledir

      Internal Options:
        --addons
        --keydir
        --e10s

    xpi
      -g, --use-config
      --static-args
      --pkgdir
      --extra-packages
      --templatedir
      --update-url
      --update-link

      Internal Options:
        --keydir

  Experimental Commands:
    develop

  Internal Commands:
    sdocs

    testcfx

    testex
      -g, --use-config
      -a, --app
      -b, --binary
      -p, --profiledir
      --dependencies
      -f, --filter
      --times

      --use-server
      --addons
      --keydir
      --test-runner-pkg

    testpkgs
      -g, --use-config
      -a, --app
      -b, --binary
      -p, --profiledir
      --dependencies
      -f, --filter
      --times

      --use-server
      --addons
      --keydir
      --test-runner-pkg

    testall
      -g, --use-config
      -a, --app
      -b, --binary
      -p, --profiledir
      --dependencies
      -f, --filter
      --times

      --use-server
      --addons
      --keydir
      --test-runner-pkg

Comment 1

[Myk Melez [:myk] [@mykmelez]]

These changes also have implications for the cfx Tool reference <https://jetpack.mozillalabs.com/sdk/0.9/docs/#guide/cfx-tool>.

Comment 2

[Drew Willcoxon :adw]

Attachment: patch

I wanted to output options per command like in comment 0, but it seems optparse can't easily list options more than once.  So this lists commands per option instead.  Each option keeps a list of the commands it supports, which is used to automatically generate the list.  In the future this would also allow `cfx --help run` to list all the options that run supports, for example.

This patch also organizes options using lists so that they can be sorted and displayed alphabetically by name.

I'll attach the output of cfx with this patch so it's easy to look over.

Comment 3

[Drew Willcoxon :adw]

Attachment: cfx output with patch applied

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 493202 [details]
cfx output with patch applied

Ah, well, this also looks pretty good.

Comment 5

[Atul Varma [:atul]]

Comment on attachment 493201 [details] [diff] [review]
patch

This patch seems to have bit-rot already, do you think you can rebase it against the current trunk?

Comment 6

[Atul Varma [:atul]]

Also, Drew, it looks like, as per my comment in bug 614128 comment 7, the --logfile and --profile-memory options will now be under the "Internal Commands and Options" classification, rather than being removed from the SDK entirely.

Comment 7

[Atul Varma [:atul]]

One semi-quick way of resolving this is to actually just have cfx --help display the raw contents of static-files/md/dev-guide/cfx-tool.md. That may be weird but at least it would get rid of the schism that currently exists between having to duplicate the docs on the Markdown and in the tool itself. Perhaps I am just being a butt, however.

Comment 8

[Drew Willcoxon :adw]

I kind of like that idea since it prevents duplication.  But it does seem like cfx-tool.md will always be a superset of cfx --help, i.e., cfx-tool.md will contain pretty much the same text as cfx --help will, but it might also describe cfx using prose, examples, etc. -- things that aren't really appropriate at the command line.  Maybe instead we could add an item to the release checklist about capturing the output of cfx --help and just copying and pasting it into cfx-tool.md?

Anyhow, I'll work on getting this patch up to date today for the beta.

Comment 9

[Atul Varma [:atul]]

Aye, true. Though one thing I've noticed about some command-line tools' help systems, e.g. "git help merge", is that they basically just show a man page, which contains all kinds of prose and examples.

I wonder, if we split up the .md file with certain invisible delimiters like the HTML-style comments and formatted them appropriately, we might be able to do something similar, such that 'cfx help' just shows a list of commands and global flags, and doing 'cfx help init' shows the particular section of the Markdown file that explains cfx init. Maybe that is going way too far/complicated though.

Comment 10

[Drew Willcoxon :adw]

Attachment: patch 2

Yeah, I would love for `cfx help` to work like that.  That's a byproduct I had in mind by associating a list of supported commands with each option.  But a full man page for each command and cfx itself would be great.

Comment 11

[Atul Varma [:atul]]

Comment on attachment 494022 [details] [diff] [review]
patch 2

Cool! I've addressed some minor issues re: what options are compatible with what commands here:

  https://github.com/toolness/jetpack-sdk/commit/9f03c9a596c208d4427b3c312d21f60085e94116

They're all basically nits, though, so feel free to push or fix the nits and push.

Comment 12

[Drew Willcoxon :adw]

Thanks, I fixed all the nits.

https://github.com/mozilla/addon-sdk/commit/d250c3a81458b7a72e208ab52044bcb10243e7c7

https://github.com/mozilla/addon-sdk/commit/6b91af1d0bd1437b8aad3e7ae29d3eda311e5bde

https://github.com/mozilla/addon-sdk/commit/84868722f4c2ad3f3a87ca59b6620ca74782336d

https://github.com/mozilla/addon-sdk/commit/4d29ad7ddf2d7eeb2708ff4a6e9d0f1504bfd74f