Skip to content

Html help pages reorg #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
kdaily wants to merge 6 commits into from
Closed

Html help pages reorg #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3093b3a
Add URL and html-based help options
kdaily Apr 22, 2025
22b1ec5
Remove unused import, format and lint
kdaily Sep 19, 2025
c19598e
Add functional tests for url, browser help modes
kdaily Sep 19, 2025
88710cd
Add unit tests
kdaily Sep 16, 2025
a38c8f8
Use elif instead of bare if
kdaily Sep 18, 2025
d4a01d8
Add comment on special case of url creation
kdaily Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions awscli/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,5 @@ def find_spec(self, fullname, path, target=None):


TopLevelImportAliasFinder.add_alias_finder(sys.meta_path)

_DEFAULT_BASE_REMOTE_URL = f"https://awscli.amazonaws.com/v2/documentation/api/{__version__}" # noqa
32 changes: 21 additions & 11 deletions awscli/clidriver.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ def _get_linux_distribution():
linux_distribution = distro.id()
version = distro.major_version()
if version:
linux_distribution += '.%s' % version
linux_distribution += f'.{version}'
except Exception:
pass
return linux_distribution
Expand Down Expand Up @@ -270,6 +270,9 @@ def _update_config_chain(self):
config_store.set_config_provider(
'cli_auto_prompt', self._construct_cli_auto_prompt_chain()
)
config_store.set_config_provider(
'cli_help_output', self._construct_cli_help_output_chain()
)

def _construct_cli_region_chain(self):
providers = [
Expand Down Expand Up @@ -308,6 +311,16 @@ def _construct_cli_output_chain(self):
]
return ChainProvider(providers=providers)

def _construct_cli_help_output_chain(self):
providers = [
ScopedConfigProvider(
config_var_name='cli_help_output',
session=self.session,
),
ConstantProvider(value='terminal'),
]
return ChainProvider(providers=providers)

def _construct_cli_pager_chain(self):
providers = [
EnvironmentProvider(
Expand Down Expand Up @@ -665,7 +678,7 @@ def _create_command_table(self):
operation_caller=CLIOperationCaller(self.session),
)
self.session.emit(
'building-command-table.%s' % self._name,
f'building-command-table.{self._name}',
command_table=command_table,
session=self.session,
command_object=self,
Expand Down Expand Up @@ -773,7 +786,7 @@ def _build_subcommand_table(self):
subcommand_table = OrderedDict()
full_name = '_'.join([c.name for c in self.lineage])
self._session.emit(
'building-command-table.%s' % full_name,
f'building-command-table.{full_name}',
command_table=subcommand_table,
session=self._session,
command_object=self,
Expand Down Expand Up @@ -803,10 +816,7 @@ def _parse_potential_subcommand(self, args, subcommand_table):
def __call__(self, args, parsed_globals):
# Once we know we're trying to call a particular operation
# of a service we can go ahead and load the parameters.
event = 'before-building-argument-table-parser.%s.%s' % (
self._parent_name,
self._name,
)
event = f'before-building-argument-table-parser.{self._parent_name}.{self._name}'
self._emit(
event,
argument_table=self.arg_table,
Expand All @@ -832,16 +842,16 @@ def __call__(self, args, parsed_globals):
remaining.append(parsed_args.help)
if remaining:
raise UnknownArgumentError(
"Unknown options: %s" % ', '.join(remaining)
f"Unknown options: {', '.join(remaining)}"
)
event = 'operation-args-parsed.%s.%s' % (self._parent_name, self._name)
event = f'operation-args-parsed.{self._parent_name}.{self._name}'
self._emit(
event, parsed_args=parsed_args, parsed_globals=parsed_globals
)
call_parameters = self._build_call_parameters(
parsed_args, self.arg_table
)
event = 'calling-command.%s.%s' % (self._parent_name, self._name)
event = f'calling-command.{self._parent_name}.{self._name}'
override = self._emit_first_non_none_response(
event,
call_parameters=call_parameters,
Expand Down Expand Up @@ -941,7 +951,7 @@ def _create_argument_table(self):
arg_object.add_to_arg_table(argument_table)
LOG.debug(argument_table)
self._emit(
'building-argument-table.%s.%s' % (self._parent_name, self._name),
f'building-argument-table.{self._parent_name}.{self._name}',
operation_model=self._operation_model,
session=self._session,
command=self,
Expand Down
59 changes: 33 additions & 26 deletions awscli/customizations/commands.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,9 +138,7 @@ def __call__(self, args, parsed_globals):
# an arg parser and parse them.
self._subcommand_table = self._build_subcommand_table()
self._arg_table = self._build_arg_table()
event = 'before-building-argument-table-parser.%s' % ".".join(
self.lineage_names
)
event = f'before-building-argument-table-parser.{".".join(self.lineage_names)}'
self._session.emit(
event,
argument_table=self._arg_table,
Expand Down Expand Up @@ -177,7 +175,7 @@ def __call__(self, args, parsed_globals):
# a chance to process and override its value.
if self._should_allow_plugins_override(cli_argument, value):
override = self._session.emit_first_non_none_response(
'process-cli-arg.%s.%s' % ('custom', self.name),
f'process-cli-arg.custom.{self.name}',
cli_argument=cli_argument,
value=value,
operation=None,
Expand All @@ -204,15 +202,15 @@ def __call__(self, args, parsed_globals):
# function for this top level command.
if remaining:
raise ParamValidationError(
"Unknown options: %s" % ','.join(remaining)
f"Unknown options: {','.join(remaining)}"
)
rc = self._run_main(parsed_args, parsed_globals)
if rc is None:
return 0
else:
return rc

def _validate_value_against_schema(self, model, value):
def _validate_value_against_schema(self, model, value): # noqa: F811
validate_parameters(value, model)

def _should_allow_plugins_override(self, param, value):
Expand All @@ -239,7 +237,7 @@ def _build_subcommand_table(self):
subcommand_table[subcommand_name] = subcommand_class(self._session)
name = '_'.join([c.name for c in self.lineage])
self._session.emit(
'building-command-table.%s' % name,
f'building-command-table.{name}',
command_table=subcommand_table,
session=self._session,
command_object=self,
Expand Down Expand Up @@ -277,7 +275,7 @@ def _build_arg_table(self):
arg_table = OrderedDict()
name = '_'.join([c.name for c in self.lineage])
self._session.emit(
'building-arg-table.%s' % name, arg_table=self.ARG_TABLE
f'building-arg-table.{name}', arg_table=self.ARG_TABLE
)
for arg_data in self.ARG_TABLE:
# If a custom schema was passed in, create the argument_model
Expand Down Expand Up @@ -328,9 +326,9 @@ def lineage(self, value):
def _raise_usage_error(self):
lineage = ' '.join([c.name for c in self.lineage])
error_msg = (
"usage: aws [options] %s <subcommand> "
f"usage: aws [options] {lineage} <subcommand> "
"[parameters]\naws: error: too few arguments"
) % lineage
)
raise ParamValidationError(error_msg)

def _add_customization_to_user_agent(self):
Expand All @@ -348,9 +346,7 @@ def __init__(
arg_table,
event_handler_class=None,
):
super(BasicHelp, self).__init__(
session, command_object, command_table, arg_table
)
super().__init__(session, command_object, command_table, arg_table)
# This is defined in HelpCommand so we're matching the
# casing here.
if event_handler_class is None:
Expand Down Expand Up @@ -383,6 +379,16 @@ def examples(self):
def event_class(self):
return '.'.join(self.obj.lineage_names)

@property
def url(self):
# If the operation command has a subcommand table with commands
# in it, treat it as a service command as opposed to an operation
# command. This is to support things like a customization command
# that rely on the `BasicHelp` object.
if len(self.command_table) > 0:
return f"{self._base_remote_url}/reference/{self.event_class.replace('.', '/')}/index.html"
return f"{self._base_remote_url}/reference/{self.event_class.replace('.', '/')}.html"

def _get_doc_contents(self, attr_name):
value = getattr(self, attr_name)
if isinstance(value, BasicCommand.FROM_FILE):
Expand All @@ -408,13 +414,18 @@ def __call__(self, args, parsed_globals):
# We pass ourselves along so that we can, in turn, get passed
# to all event handlers.
docevents.generate_events(self.session, self)
self.renderer.render(self.doc.getvalue())

if self._help_output_format == 'url':
self.renderer.render(self.url.encode())
else:
self.renderer.render(self.doc.getvalue())

instance.unregister()


class BasicDocHandler(OperationDocumentEventHandler):
def __init__(self, help_command):
super(BasicDocHandler, self).__init__(help_command)
super().__init__(help_command)
self.doc = help_command.doc

def doc_description(self, help_command, **kwargs):
Expand All @@ -424,9 +435,7 @@ def doc_description(self, help_command, **kwargs):

def doc_synopsis_start(self, help_command, **kwargs):
if not help_command.synopsis:
super(BasicDocHandler, self).doc_synopsis_start(
help_command=help_command, **kwargs
)
super().doc_synopsis_start(help_command=help_command, **kwargs)
else:
self.doc.style.h2('Synopsis')
self.doc.style.start_codeblock()
Expand All @@ -447,14 +456,14 @@ def doc_synopsis_option(self, arg_name, help_command, **kwargs):
)
self._documented_arg_groups.append(argument.group_name)
elif argument.cli_type_name == 'boolean':
option_str = '%s' % argument.cli_name
option_str = f'{argument.cli_name}'
elif argument.nargs == '+':
option_str = "%s <value> [<value>...]" % argument.cli_name
option_str = f"{argument.cli_name} <value> [<value>...]"
else:
option_str = '%s <value>' % argument.cli_name
option_str = f'{argument.cli_name} <value>'
if not (argument.required or argument.positional_arg):
option_str = '[%s]' % option_str
doc.writeln('%s' % option_str)
option_str = f'[{option_str}]'
doc.writeln(f'{option_str}')

else:
# A synopsis has been provided so we don't need to write
Expand All @@ -463,9 +472,7 @@ def doc_synopsis_option(self, arg_name, help_command, **kwargs):

def doc_synopsis_end(self, help_command, **kwargs):
if not help_command.synopsis and not help_command.command_table:
super(BasicDocHandler, self).doc_synopsis_end(
help_command=help_command, **kwargs
)
super().doc_synopsis_end(help_command=help_command, **kwargs)
else:
self.doc.style.end_codeblock()

Expand Down
Loading
Loading