File: //snap/google-cloud-cli/current/lib/surface/meta/generate_help_docs.py
# -*- coding: utf-8 -*- #
# Copyright 2015 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.
"""A command that generates and/or updates help document directoriess."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import re
from googlecloudsdk.calliope import base
from googlecloudsdk.calliope import walker_util
from googlecloudsdk.command_lib.meta import help_util
from googlecloudsdk.core import exceptions
from googlecloudsdk.core import log
from googlecloudsdk.core.console import console_attr
class HelpOutOfDateError(exceptions.Error):
"""Help documents out of date for --test."""
class GenerateHelpDocs(base.Command):
"""Generate and/or update help document directories.
The DevSite docs are generated in the --devsite-dir directory with pathnames
in the reference directory hierarchy. The manpage docs are generated in the
--manpage-dir directory with pathnames in the manN/ directory hierarchy.
"""
@staticmethod
def Args(parser):
parser.add_argument(
'--hidden',
action='store_true',
default=False,
help=('Include documents for hidden commands and groups.'))
parser.add_argument(
'--devsite-dir',
metavar='DIRECTORY',
help=('The directory where the generated DevSite reference document '
'subtree will be written. If not specified then DevSite '
'documents will not be generated.'))
parser.add_argument(
'--help-text-dir',
metavar='DIRECTORY',
help=('The directory where the generated help text reference document '
'subtree will be written. If not specified then help text '
'documents will not be generated. The --hidden flag is implied '
'for --help-text-dir.'))
parser.add_argument(
'--html-dir',
metavar='DIRECTORY',
help=('The directory where the standalone manpage HTML files will be '
'generated. index.html contains manpage tree navigation in the '
'left pane. The active command branch and its immediate children '
'are visible and clickable. Hover to navigate the tree. Run '
'`python -m http.server 8888 &` in DIRECTORY and point '
'your browser at [](http://localhost:8888) to view the manpage '
'tree. If not specified then the HTML manpage site will not be '
'generated.'))
parser.add_argument(
'--linter-dir',
metavar='DIRECTORY',
help=('The directory where the generated documentation linter errors '
'for the help text reference document subtree will be written. '
'If not specified then documentation linter documents will not '
'be generated.'))
parser.add_argument(
'--manpage-dir',
metavar='DIRECTORY',
help=('The directory where the generated manpage document subtree will '
'be written. The manpage hierarchy is flat with all command '
'documents in the manN/ subdirectory. If not specified then '
'manpage documents will not be generated.'))
parser.add_argument(
'--test',
action='store_true',
help=('Show but do not apply --update actions. Exit with non-zero exit '
'status if any help document file must be updated.'))
parser.add_argument(
'--update',
action='store_true',
default=False,
help=('Update destination directories to match the current CLI. '
'Documents for commands not present in the current CLI will be '
'deleted. Use this flag to update the help text golden files '
'after the help_text_test test fails.'))
parser.add_argument(
'--update-help-text-dir',
hidden=True,
metavar='DIRECTORY',
help='Deprecated. Use --update --help-text-dir=DIRECTORY instead.')
parser.add_argument(
'restrict',
metavar='COMMAND/GROUP',
nargs='*',
default=None,
help=("""Restrict document generation to these dotted command paths.
For example:
gcloud.alpha gcloud.beta.test
OR
gcloud.{alpha.,beta.,}compute.instances
"""))
def Run(self, args):
out_of_date = set()
def Generate(kind, generator, directory, encoding='utf-8', hidden=False):
"""Runs generator and optionally updates help docs in directory."""
restrict_dir = [re.sub(r'_', r'-', p) for p in args.restrict]
console_attr.ResetConsoleAttr(encoding)
if not args.update:
generator(
self._cli_power_users_only, directory, restrict=restrict_dir
).Walk(hidden, restrict_dir)
elif help_util.HelpUpdater(
self._cli_power_users_only, directory, generator,
test=args.test, hidden=hidden).Update(restrict_dir):
out_of_date.add(kind)
# Handle deprecated flags -- probably burned in a bunch of eng scripts.
if args.update_help_text_dir:
log.warning('[--update-help-text-dir={directory}] is deprecated. Use '
'this instead: --update --help-text-dir={directory}.'.format(
directory=args.update_help_text_dir))
args.help_text_dir = args.update_help_text_dir
args.update = True
# Generate/update the destination document directories.
if args.devsite_dir:
Generate('DevSite', walker_util.DevSiteGenerator, args.devsite_dir,
hidden=args.hidden)
if args.help_text_dir:
Generate('help text', walker_util.HelpTextGenerator, args.help_text_dir,
'ascii', hidden=True)
if args.html_dir:
Generate('html', walker_util.HtmlGenerator, args.html_dir,
hidden=args.hidden)
if args.manpage_dir:
Generate('man page', walker_util.ManPageGenerator, args.manpage_dir,
hidden=args.hidden)
if args.linter_dir:
Generate('command linter', walker_util.LinterGenerator, args.linter_dir,
hidden=args.hidden)
# Test update fails with an exception if documents are out of date.
if out_of_date and args.test:
names = sorted(out_of_date)
if len(names) > 1:
kinds = ' and '.join([', '.join(names[:-1]), names[-1]])
else:
kinds = names[0]
raise HelpOutOfDateError(
'{} document files must be updated.'.format(kinds))