91 lines
3.3 KiB
Python
91 lines
3.3 KiB
Python
# -*- coding: utf-8 -*- #
|
|
# Copyright 2018 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.
|
|
|
|
"""Supplementary help for setting up gcloud offline help."""
|
|
|
|
from __future__ import absolute_import
|
|
from __future__ import division
|
|
from __future__ import unicode_literals
|
|
|
|
from googlecloudsdk.calliope import base
|
|
|
|
|
|
class OfflineHelp(base.TopicCommand):
|
|
"""Setting up gcloud command offline help.
|
|
|
|
There are many ways to access `gcloud` command help. Only the first requires
|
|
online access:
|
|
|
|
* Browse https://cloud.google.com/sdk/gcloud/reference/ for the most
|
|
recent Google Cloud CLI release online documents.
|
|
|
|
* Add the *--help* flag to any command. This will render a man style
|
|
document in a terminal pager. The document is always up to date with the
|
|
command because it is generated by collating help text from the command
|
|
itself.
|
|
|
|
* Use the `gcloud beta interactive` shell which has as-you-type help. Like
|
|
*--help*, the interactive help documents are always up to date with the
|
|
`gcloud` installation.
|
|
|
|
* Generate HTML documents in a local directory and point your browser to
|
|
the generated *index.html* for offline browsing. Hover over a navigation
|
|
item to focus the menu, hover to the left to expand it again. More
|
|
details on this below.
|
|
|
|
* Generate and install *man*(1) style documents on a local host. More
|
|
details on this below.
|
|
|
|
All of these methods have the same content, all generated from a Google Cloud
|
|
CLI `gcloud` installation. The last two are user maintained and can become out
|
|
of date. Either use them for one time offline access, or make them part of
|
|
your Google Cloud CLI installation/update routine.
|
|
|
|
### Generating offline HTML documents
|
|
|
|
To generate HTML documents for offline browsing:
|
|
|
|
# Select an empty directory where the HTML and supporting *.css* and
|
|
# *.js* files will be generated.
|
|
HTML_DIR=<some-local-directory>
|
|
|
|
# Generate the HTML in $HTML_DIR.
|
|
# Should take ~1 min, 10 min or more on slower systems.
|
|
gcloud meta generate-help-docs --html-dir=$HTML_DIR
|
|
|
|
Then enter this URL in the browser address/search bar, where $HTML_DIR
|
|
must be the actual path name of the directory:
|
|
|
|
file://$HTML_DIR/index.html
|
|
|
|
### Generating offline manpage documents
|
|
|
|
To generate man page documents for the *man*(1) command:
|
|
|
|
# Select an empty directory where the man page files will be generated.
|
|
MANPAGE_DIR=<some-local-directory>
|
|
|
|
# Generate the man pages in $MANPAGE_DIR.
|
|
# Should take ~1 min, 10 min or more on slower systems.
|
|
gcloud meta generate-help-docs --manpage-dir=$MANPAGE_DIR
|
|
|
|
# Append $MANPAGE_DIR to the MANPATH environment variable:
|
|
export MANPATH=$MANPATH:$MANPAGE_dir
|
|
|
|
Then run the man command on gcloud manpages:
|
|
|
|
man gcloud info
|
|
"""
|