help text for juju needs improving

[Peter Matulis]

This text should appear with `juju help`.

e.g.:

Usage: juju [help] <command>

Summary:
Juju is model & service management software designed to leverage the power of existing resource pools, particularly cloud-based ones. It has built-in support for cloud providers such as Amazon EC2, Google GCE, Microsoft Azure, OpenStack, and Rackspace. It also works very well with MAAS and LXD. Juju allows for easy installation and management of workloads on a chosen resource pool.

See https://jujucharms.com/docs/stable/help for documentation.

Common commands:

    add-credential Adds or replaces credentials for a cloud.
    add-relation Adds a relation between two services.
    add-unit Adds extra units of a deployed service.
    add-user Adds a Juju user to a controller.
    bootstrap Initializes a cloud environment.
    create-model Creates a hosted model.
    deploy Deploys a new service.
    expose Makes a service publicly available over the network.
    list-controllers Lists all controllers.
    list-models Lists models a user can access on a controller.
    status Displays the current status of Juju, services, and units.
    switch Selects or identifies the current controller and model.

Example help commands:

    `juju help` This help page
    `juju help commands` Lists all commands
    `juju help deploy` Shows help for command 'deploy'

[Reed O'Brien (reedobrien)]

This has a multi line summary. I imagine this will be broken up to have a single line summary and the rest placed under details. Also it looks at a glance like the commands and options are dynamically generated. So they will appear regardless -- unless we rewrite how the command works.

Please advise.

[Nick Veitch (evilnick)]

I'm not entirely sure how the current help is generated, but it doesn't
have any headings etc. Can the summary be blank?
We can skip off the Summary heading too, and just have all that text in the
body so the output looks like:

"
  Usage: juju [help] <command>

Juju is model & service management software designed to leverage the power
of existing resource pools, particularly cloud-based ones. It has built-in
support for cloud providers such as Amazon EC2, Google GCE, Microsoft
Azure, OpenStack, and Rackspace. It also works very well with MAAS and LXD.
Juju allows for easy installation and management of workloads on a chosen
resource pool.

"

On 14 April 2016 at 00:33, Reed O'Brien <email address hidden> wrote:

> This has a multi line summary. I imagine this will be broken up to have
> a single line summary and the rest placed under details. Also it looks
> at a glance like the commands and options are dynamically generated. So
> they will appear regardless -- unless we rewrite how the command works.
>
> Please advise.
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1568862
>
> Title:
> help text for juju needs improving
>
> Status in juju-core:
> Triaged
>
> Bug description:
> This text should appear with `juju help`.
>
> e.g.:
>
> Usage: juju [help] <command>
>
> Summary:
> Juju is model & service management software designed to leverage the
> power of existing resource pools, particularly cloud-based ones. It has
> built-in support for cloud providers such as Amazon EC2, Google GCE,
> Microsoft Azure, OpenStack, and Rackspace. It also works very well with
> MAAS and LXD. Juju allows for easy installation and management of workloads
> on a chosen resource pool.
>
> See https://jujucharms.com/docs/stable/help for documentation.
>
> Common commands:
>
> add-credential Adds or replaces credentials for a cloud.
> add-relation Adds a relation between two services.
> add-unit Adds extra units of a deployed service.
> add-user Adds a Juju user to a controller.
> bootstrap Initializes a cloud environment.
> create-model Creates a hosted model.
> deploy Deploys a new service.
> expose Makes a service publicly available over the
> network.
> list-controllers Lists all controllers.
> list-models Lists models a user can access on a controller.
> status Displays the current status of Juju, services, and
> units.
> switch Selects or identifies the current controller and
> model.
>
> Example help commands:
>
> `juju help` This help page
> `juju help commands` Lists all commands
> `juju help deploy` Shows help for command 'deploy'
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/juju-core/+bug/1568862/+subscriptions
>

--
Nick Veitch,
CDO Documentation
Canonical

[Reed O'Brien (reedobrien)]

Looking into the code behind it, this command works differently than the subcommands.

Output:

Usage: juju [help] <command>

Summary:
Juju is model & service management software designed to leverage the power
of existing resource pools, particularly cloud-based ones. It has built-ini
support for cloud providers such as Amazon EC2, Google GCE, Microsoft
Azure, OpenStack, and Rackspace. It also works very well with MAAS and
LXD. Juju allows for easy installation and management of workloads on a
chosen resource pool.

See https://jujucharms.com/docs/stable/help for documentation.

Common commands:

    add-credential Adds or replaces credentials for a cloud.
    add-relation Adds a relation between two services.
    add-unit Adds extra units of a deployed service.
    add-user Adds a Juju user to a controller.
    bootstrap Initializes a cloud environment.
    create-model Creates a hosted model.
    deploy Deploys a new service.
    expose Makes a service publicly available over the network.
    list-controllers Lists all controllers.
    list-models Lists models a user can access on a controller.
    status Displays the current status of Juju, services, and units.
    switch Selects or identifies the current controller and model.

Example help commands:

    `juju help` This help page
    `juju help commands` Lists all commands
    `juju help deploy` Shows help for command 'deploy'

[Reed O'Brien (reedobrien)]

Sorry typo in above. Output:

Usage: juju [help] <command>

Summary:
Juju is model & service management software designed to leverage the power
of existing resource pools, particularly cloud-based ones. It has built-in
support for cloud providers such as Amazon EC2, Google GCE, Microsoft
Azure, OpenStack, and Rackspace. It also works very well with MAAS and
LXD. Juju allows for easy installation and management of workloads on a
chosen resource pool.

See https://jujucharms.com/docs/stable/help for documentation.

Common commands:

    add-credential Adds or replaces credentials for a cloud.
    add-relation Adds a relation between two services.
    add-unit Adds extra units of a deployed service.
    add-user Adds a Juju user to a controller.
    bootstrap Initializes a cloud environment.
    create-model Creates a hosted model.
    deploy Deploys a new service.
    expose Makes a service publicly available over the network.
    list-controllers Lists all controllers.
    list-models Lists models a user can access on a controller.
    status Displays the current status of Juju, services, and units.
    switch Selects or identifies the current controller and model.

Example help commands:

    `juju help` This help page
    `juju help commands` Lists all commands
    `juju help deploy` Shows help for command 'deploy'

[Peter Matulis (petermatulis)]

You mean the text cannot be aligned? The current (old) text is aligned (?).

[Reed O'Brien (reedobrien)]

I used the copy and formatting from the bug description. The bit after
"This text should appear with `juju help`.

e.g.:"

So I am not sure what you mean. Can you elaborate?

[Reed O'Brien (reedobrien)]

I think I understand, but would prefer not to guess.

[Reed O'Brien (reedobrien)]

I assume you mean like (probably won't appear aligned unless you use a fixed width font):

Usage: juju [help] <command>

Summary:
Juju is model & service management software designed to leverage the power
of existing resource pools, particularly cloud-based ones. It has built-in
support for cloud providers such as Amazon EC2, Google GCE, Microsoft
Azure, OpenStack, and Rackspace. It also works very well with MAAS and
LXD. Juju allows for easy installation and management of workloads on a
chosen resource pool.

See https://jujucharms.com/docs/stable/help for documentation.

Common commands:

    add-credential Adds or replaces credentials for a cloud.
    add-relation Adds a relation between two services.
    add-unit Adds extra units of a deployed service.
    add-user Adds a Juju user to a controller.
    bootstrap Initializes a cloud environment.
    create-model Creates a hosted model.
    deploy Deploys a new service.
    expose Makes a service publicly available over the network.
    list-controllers Lists all controllers.
    list-models Lists models a user can access on a controller.
    status Displays the current status of Juju, services, and units.
    switch Selects or identifies the current controller and model.

Example help commands:

    `juju help` This help page
    `juju help commands` Lists all commands
    `juju help deploy` Shows help for command 'deploy'

[Peter Matulis (petermatulis)]

When I filed the bug everything was aligned. When I try to edit everything is aligned again. So I made a screenshot:

https://private-fileshare.canonical.com/~pmatulis/doc_team/bug_1568862.png

[Reed O'Brien (reedobrien)]

This is aligned on my terminal... Should be on your's once it is updated...:

Usage: juju [help] <command>

Summary:
Juju is model & service management software designed to leverage the power
of existing resource pools, particularly cloud-based ones. It has built-in
support for cloud providers such as Amazon EC2, Google GCE, Microsoft
Azure, OpenStack, and Rackspace. It also works very well with MAAS and
LXD. Juju allows for easy installation and management of workloads on a
chosen resource pool.

See https://jujucharms.com/docs/stable/help for documentation.

Common commands:

    add-credential Adds or replaces credentials for a cloud.
    add-relation Adds a relation between two services.
    add-unit Adds extra units of a deployed service.
    add-user Adds a Juju user to a controller.
    bootstrap Initializes a cloud environment.
    create-model Creates a hosted model.
    deploy Deploys a new service.
    expose Makes a service publicly available over the network.
    list-controllers Lists all controllers.
    list-models Lists models a user can access on a controller.
    status Displays the current status of Juju, services, and units.
    switch Selects or identifies the current controller and model.

Example help commands:

    `juju help` This help page
    `juju help commands` Lists all commands
    `juju help deploy` Shows help for command 'deploy'

[Reed O'Brien (reedobrien)]

Here's a screenshot back to show the alignment.