Documentation by Object

[tnelson-doghouse]

Is your feature request related to a problem? Please describe.
I often what to know what objects I can operate on, and what I can do to them

Describe the solution you'd like
If the docs had a page for each object (eg, "project", "user"), and listed:

• The commands for directly operating on them (eg. lagoon add project)
• The commands that link them to things (eg. lagoon add project-group)
  ...that'd be great.

Each command should just have a short description (ie. one line), and link to the main command page

Describe alternatives you've considered
Digging through the docs like I do now.

[shreddedbacon]

One problem with that, the docs are currently automatically generated from the CLI structure using cobra.

To do what you suggest would mean manual documentation changes, which we kind of want to avoid due to issues it brings.

Generally though the short description of commands should provide enough information to show references, for example looking at lagoon add the short description says which ones can be used on project and which ones are for users. We could improve these descriptions in some cases though potentially.

$ lagoon add
Add a project, or add notifications and variables to projects or environments

Usage:
  lagoon add [command]

Aliases:
  add, a

Available Commands:
  deploytarget               Add a DeployTarget to lagoon
  deploytarget-config        Add deploytarget config to a project
  group                      Add a group to Lagoon, or add a group to an organization
  notification               Add notifications or add notifications to projects
  organization               Add a new organization to Lagoon
  organization-administrator Add an administrator to an Organization
  organization-deploytarget  Add a deploy target to an Organization
  project                    Add a new project to Lagoon, or add a project to an organization
  project-group              Add a project to a group in lagoon
  user                       Add a user to lagoon
  user-group                 Add a user to a group in lagoon
  user-sshkey                Add an SSH key to a user
  variable            Add or update a variable to an environment or project

I know that isn't really ideal or solves your particular issue of having a list of commands that can be used on specific resources in Lagoon, but the alternative is potentially out of date documentation pages because the auto-generated docs won't update pages manually created.

[tnelson-doghouse]

I agree with the goal of auto-generation, but wouldn't it be possible to set up an additional automatic generation where:

• Each command is marked with an object (and the default object is "other")
• A second set of documentation is generated that pulls out those summaries and crosslinks to the original documentation
• Just possibly, a writeup on (or link to a writeup on) each object. These writeups/links would have to be manually maintained, but hopefully this would only be relevant when adding a new object

Cobra might not do that easily (XSLT would do it, but people seem to have turned their backs on XML just because it's better at documents than at being an on-the-wire protocol).

HTH,

[shreddedbacon]

Cobra generates the documentation based on the command structure. The only way to do what you are wanting here is to re-write the CLI with the command structure laid out in a different manner to the way they currently are, OR write some entirely new functionality outside of the CLI that would still need to be maintained in addition to maintaining the commands themselves.

As it stands, I'm fairly confident this will not be resolvable in the short term in the current implementation of the CLI, and the team just doesn't have the resources available to invest in writing out an entirely separate autogeneration system to satisfy this level of documentation changes without considerable changes as described above. I will add this as a possible thing to consider when we think about re-writing the CLI in the future, but no guarantee that it will happen, but the rewrite (when/if it happens) will hopefully make things a bit clearer (and no there is no open issue or tracker for a rewrite, because there is no guarantee that we will do a rewrite at this point in time).

Alternatively, if you've got the time to invest in working out how this could work in the current implementation, we're always open to reviewing pull requests, but that does not guarantee a merge either. Just wanting to set expectations around the work involved on this.

[tnelson-doghouse]

Sure, fair enough. This sounds like a Cobra problem, not an Amazee problem. Thanks.

[shreddedbacon]

This sounds like a Cobra problem

Well, not really. Cobra just builds the documentation based on the command structure, it does what it does and it does it well.

The problem you're describing is not a problem that I think cobra can solve. Cobra doesn't understand that one command could be linked to a specific object or not, because it doesn't exist in cobra.

[tnelson-doghouse]

So the problem is that cobra only understands commands, not objects. Still sounds like a cobra problem :p .