def validate_verdi_documentation():
"""Auto-generate the documentation for `verdi` through `click`."""
from click import Context
from aiida.cmdline.commands.cmd_verdi import verdi
# Set the `verdi data` command to isolated mode such that external plugin commands are not discovered
ctx = Context(verdi)
command = verdi.get_command(ctx, 'data')
command.set_exclude_external_plugins(True)
# Replacing the block with the overview of `verdi`
filepath_verdi_overview = os.path.join(ROOT_DIR, 'docs', 'source', 'working_with_aiida', 'index.rst')
overview_block_start_marker = '.. _verdi_overview:'
overview_block_end_marker = '.. END_OF_VERDI_OVERVIEW_MARKER'
# Generate the new block with the command index
block = []
for name, command in sorted(verdi.commands.items()):
short_help = command.help.split('\n')[0]
block.append(u'* :ref:`{name:}<verdi_{name:}>`: {help:}\n'.format(name=name, help=short_help))
# New block should start and end with an empty line after and before the literal block marker
block.insert(0, u'\n')
block.append(u'\n')
replace_block_in_file(filepath_verdi_overview, overview_block_start_marker, overview_block_end_marker, block)
# Replacing the block with the commands of `verdi`
filepath_verdi_commands = os.path.join(ROOT_DIR, 'docs', 'source', 'verdi', 'verdi_user_guide.rst')
commands_block_start_marker = '.. _verdi_commands:'
commands_block_end_marker = '.. END_OF_VERDI_COMMANDS_MARKER'
# Generate the new block with the command help strings
header = u'Commands'
message = u'Below is a list with all available subcommands.'
block = [u'{}\n{}\n{}\n\n'.format(header, '=' * len(header), message)]
for name, command in sorted(verdi.commands.items()):
ctx = click.Context(command)
header_label = u'.. _verdi_{name:}:'.format(name=name)
header_string = u'``verdi {name:}``'.format(name=name)
header_underline = u'-' * len(header_string)
block.append(header_label + '\n\n')
block.append(header_string + '\n')
block.append(header_underline + '\n\n')
block.append(u'::\n\n') # Mark the beginning of a literal block
for line in ctx.get_help().split('\n'):
if line:
block.append(u' {}\n'.format(line))
else:
block.append(u'\n')
block.append(u'\n\n')
# New block should start and end with an empty line after and before the literal block marker
block.insert(0, u'\n')
block.append(u'\n')
replace_block_in_file(filepath_verdi_commands, commands_block_start_marker, commands_block_end_marker, block)
def validate_verdi_documentation():
"""Auto-generate the documentation for `verdi` through `click`."""
from click import Context
from aiida.cmdline.commands.cmd_verdi import verdi
width = 90 # The maximum width of the formatted help strings in characters
# Set the `verdi data` command to isolated mode such that external plugin commands are not discovered
ctx = Context(verdi, terminal_width=width)
command = verdi.get_command(ctx, 'data')
command.set_exclude_external_plugins(True)
# Replacing the block with the commands of `verdi`
filepath_verdi_commands = os.path.join(ROOT_DIR, 'docs', 'source',
'reference', 'command_line.rst')
commands_block_start_marker = '.. _reference:command-line:verdi:'
commands_block_end_marker = '.. END_OF_VERDI_COMMANDS_MARKER'
# Generate the new block with the command help strings
header = 'Commands'
message = 'Below is a list with all available subcommands.'
block = ['{}\n{}\n{}\n\n'.format(header, '=' * len(header), message)]
for name, command in sorted(verdi.commands.items()):
ctx = click.Context(command, terminal_width=width)
header_label = '.. _reference:command-line:verdi-{name:}:'.format(
name=name)
header_string = '``verdi {name:}``'.format(name=name)
header_underline = '-' * len(header_string)
block.append(header_label + '\n\n')
block.append(header_string + '\n')
block.append(header_underline + '\n\n')
block.append(
'.. code:: console\n\n') # Mark the beginning of a literal block
for line in ctx.get_help().split('\n'):
if line:
block.append(' {}\n'.format(line))
else:
block.append('\n')
block.append('\n\n')
# New block should start and end with an empty line after and before the literal block marker
block.insert(0, '\n')
block.append('\n')
replace_block_in_file(filepath_verdi_commands, commands_block_start_marker,
commands_block_end_marker, block)
def verdi_help(ctx, command):
"""Show help for given command."""
cmdctx = ctx.parent
if command:
cmd = verdi.get_command(ctx.parent, command)
if not cmd:
# we should never end up here since verdi.get_command(...) gives
# suggestions if the command could not be found and calls click.fail
echo.echo_critical("command '{}' not found".format(command))
cmdctx = click.Context(cmd, info_name=cmd.name, parent=ctx.parent)
echo.echo(cmdctx.get_help())