82 lines
3.2 KiB
Python
82 lines
3.2 KiB
Python
# -*- coding: utf-8 -*- #
|
|
# Copyright 2017 Google LLC. All Rights Reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""CLI trees supplementary help."""
|
|
|
|
from __future__ import absolute_import
|
|
from __future__ import division
|
|
from __future__ import unicode_literals
|
|
|
|
from googlecloudsdk.calliope import base
|
|
|
|
|
|
# NOTE: If the name of this topic is modified, please make sure to update all
|
|
# references to it in error messages and other help messages as there are no
|
|
# tests to catch such changes.
|
|
class CliTrees(base.TopicCommand):
|
|
"""CLI trees supplementary help.
|
|
|
|
CLI trees are static nested dictionaries that describe all of the groups,
|
|
commands, flags, positionals, help text, and completer module paths for a
|
|
CLI. A CLI tree is often much faster to load and access than one generated
|
|
at runtime from an active CLI. It is also a more compact representation.
|
|
A properly formed CLI tree can be used to reproduce the help documentation
|
|
for an entire CLI.
|
|
|
|
### CLI Tree Data Files
|
|
|
|
A CLI tree is a dictionary in a JSON file. By convention, the file base name
|
|
is the corresponding CLI name. For example, the CLI tree file name for
|
|
*gcloud* is *gcloud.json*.
|
|
|
|
CLI trees associated with Google Cloud CLI modules are installed in the
|
|
*data/cli* subdirectory of the Google Cloud CLI installation root:
|
|
|
|
$(gcloud info --format="value(installation.sdk_root)")/data/cli
|
|
|
|
This includes tree data for *gcloud* (core component), *bq*, *gsutil*,
|
|
and *kubectl*. Note that the tree data is installed with the component.
|
|
If the component is not installed then neither is its CLI tree. An installed
|
|
component does not require its CLI tree to run. Only the *gcloud* CLI
|
|
tree is required by `$ gcloud alpha interactive`.
|
|
|
|
By default, CLI trees for other commands are JSON files generated on demand
|
|
from their *man*(1) or *man7.org* man pages. They are cached in the *cli*
|
|
subdirectory of the global config directory:
|
|
|
|
$(gcloud info --format="value(config.paths.global_config_dir)")/cli
|
|
|
|
### The gcloud CLI Tree
|
|
|
|
The *gcloud* CLI tree is used for static TAB completion, the corpus for
|
|
`$ gcloud alpha help-search`, and the data source for
|
|
`$ gcloud alpha interactive` completions and help text generation.
|
|
|
|
### Other CLI Trees
|
|
|
|
`$ gcloud alpha interactive` uses CLI tree data files for typeahead,
|
|
command line completion and active help. A few CLI trees are installed
|
|
with their respective Google Cloud CLI components: *gcloud* (core component),
|
|
*bq*, *gsutil*, and *kubectl*.
|
|
|
|
The generated trees are a close approximation. You can construct your own,
|
|
especially for hierarchical CLIs like *git*(1) that are hard to extract
|
|
from man pages.
|
|
|
|
### CLI Tree Schema
|
|
|
|
TBD (`gcloud interactive` is still in ALPHA).
|
|
"""
|