Improve Main Team documentation by adding the available flags

[dcsg]

Docs rendered:

[vito]

Thanks! This is a great start, but my one concern is that there are actually many more --main-team- flags:

          --main-team-local-user=USERNAME                                                                       A whitelisted local concourse user. These
      -c, --main-team-config=                                                                                   Configuration file for specifying team
          --main-team-bitbucket-cloud-user=USERNAME                                                             A whitelisted Bitbucket Cloud user
          --main-team-bitbucket-cloud-team=TEAM_NAME                                                            A whitelisted Bitbucket Cloud team
          --main-team-cf-user=USERNAME                                                                          A whitelisted CloudFoundry user
          --main-team-cf-org=ORG_NAME                                                                           A whitelisted CloudFoundry org
          --main-team-cf-space=ORG_NAME:SPACE_NAME                                                              (Deprecated) A whitelisted CloudFoundry
          --main-team-cf-space-with-any-role=ORG_NAME:SPACE_NAME                                                A whitelisted CloudFoundry space for users
          --main-team-cf-space-with-developer-role=ORG_NAME:SPACE_NAME                                          A whitelisted CloudFoundry space for users
          --main-team-cf-space-with-auditor-role=ORG_NAME:SPACE_NAME                                            A whitelisted CloudFoundry space for users
          --main-team-cf-space-with-manager-role=ORG_NAME:SPACE_NAME                                            A whitelisted CloudFoundry space for users
          --main-team-cf-space-guid=SPACE_GUID                                                                  A whitelisted CloudFoundry space guid
          --main-team-github-user=USERNAME                                                                      A whitelisted GitHub user
          --main-team-github-org=ORG_NAME                                                                       A whitelisted GitHub org
          --main-team-github-team=ORG_NAME:TEAM_NAME                                                            A whitelisted GitHub team
          --main-team-gitlab-user=USERNAME                                                                      A whitelisted GitLab user
          --main-team-gitlab-group=GROUP_NAME                                                                   A whitelisted GitLab group
          --main-team-ldap-user=USERNAME                                                                        A whitelisted LDAP user
          --main-team-ldap-group=GROUP_NAME                                                                     A whitelisted LDAP group
          --main-team-microsoft-user=USERNAME                                                                   A whitelisted Microsoft user
          --main-team-microsoft-group=GROUP_NAME                                                                A whitelisted Microsoft group
          --main-team-oauth-user=USERNAME                                                                       A whitelisted OAuth2 user
          --main-team-oauth-group=GROUP_NAME                                                                    A whitelisted OAuth2 group
          --main-team-oidc-user=USERNAME                                                                        A whitelisted OIDC user
          --main-team-oidc-group=GROUP_NAME                                                                     A whitelisted OIDC group

The docs currently cover this pretty indirectly - they point you to fly set-team and say "use the same flags but prefixed with --main-team-" - while the set of flags is actually documented in a section for each auth provider, e.g. the GitHub flags.

I definitely think it'd be easier to see all the flags at once, but I wonder if this is really just another thing that would benefit from having an exhaustive reference of all the flags you can set. 🤔

In any case, I'm a little worried about only documenting a couple of them. Maybe we could include a couple of them as examples (to show the --main-team- prefix) and provide a more direct reference to the auth provider docs so the rest of the flags are easier to discover?

[dcsg]

I definitely think it'd be easier to see all the flags at once, but I wonder if this is really just another thing that would benefit from having an exhaustive reference of all the flags you can set. 🤔

IMO I think it would be much easier to have a place where you can find all the configuration reference to all flags. Saying that for this case IMO we should show an example like you mention and then add a link to the reference page.

In any case, I'm a little worried about only documenting a couple of them. Maybe we could include a couple of them as examples (to show the --main-team- prefix) and provide a more direct reference to the auth provider docs so the rest of the flags are easier to discover?

Yup, I do agree with this.

Btw the the GitHub flags link is pointing to localhost 😅