def check_modified_affects_all(rootdir):
"""Check whether special files were modified.
There are some special files where we should rebuild all books
if either of these is touched.
"""
os.chdir(rootdir)
try:
git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"]
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
special_files = [
# Top-Level pom.xml
"pom.xml",
# doc/pom.xml in openstack-manuals
"doc/pom.xml"
]
for f in modified_files:
if f in special_files or f.endswith('.ent'):
if cfg.CONF.verbose:
print("File %s modified, this affects all books." % f)
return True
return False
def www_touched(check_only_www):
"""Check whether files in www directory are touched.
If check_only_www is True: Check that only files in www are touched.
Otherwise check that files in www are touched.
"""
try:
git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"]
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
www_changed = False
other_changed = False
for f in modified_files:
if f.startswith("www/"):
www_changed = True
else:
other_changed = True
if check_only_www:
return www_changed and not other_changed
return www_changed
def check_modified_affects_all(rootdir):
"""Check whether special files were modified.
There are some special files where we should rebuild all books
if either of these is touched.
"""
os.chdir(rootdir)
try:
git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"]
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
special_files = [
# Top-Level pom.xml
"pom.xml",
# doc/pom.xml in openstack-manuals
"doc/pom.xml"
]
for f in modified_files:
if f in special_files or f.endswith('.ent'):
if cfg.CONF.verbose:
print("File %s modified, this affects all books." % f)
return True
return False
def www_touched(check_only_www):
"""Check whether files in www directory are touched.
If check_only_www is True: Check that only files in www are touched.
Otherwise check that files in www are touched.
"""
try:
git_args = ["git", "diff", "--name-only", "HEAD~1", "HEAD"]
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
www_changed = False
other_changed = False
for f in modified_files:
if f.startswith("www/"):
www_changed = True
else:
other_changed = True
if check_only_www:
return www_changed and not other_changed
return www_changed
def generate_subcommands(os_command, os_file, blacklist, only_subcommands,
extra_params, suffix, title_suffix):
"""Convert os_command help subcommands for all subcommands to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
:param blacklist: list of elements that will not be documented
:param only_subcommands: if not empty, list of subcommands to document
:param extra_params: Extra parameter to pass to os_command.
:param suffix: Extra suffix to add to xml:id
:param title_suffix: Extra suffix for title
"""
print("Documenting '%s' subcommands..." % os_command)
blacklist.append("bash-completion")
blacklist.append("complete")
blacklist.append("help")
if not only_subcommands:
args = [os_command]
if extra_params:
args.extend(extra_params)
args.append("bash-completion")
all_options = check_output(args).strip().split()
else:
all_options = only_subcommands
subcommands = [
o for o in all_options if not (o.startswith('-') or o in blacklist)
]
for subcommand in sorted(subcommands):
generate_subcommand(os_command, subcommand, os_file, extra_params,
suffix, title_suffix)
print("%d subcommands documented." % len(subcommands))
def generate_subcommands(os_command, os_file, blacklist, only_subcommands):
"""Convert os_command help subcommands for all subcommands to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
:param blacklist: list of elements that will not be documented
:param only_subcommands: if not empty, list of subcommands to document
"""
print("Documenting '%s' subcommands..." % os_command)
blacklist.append("bash-completion")
blacklist.append("complete")
blacklist.append("help")
if not only_subcommands:
all_options = check_output([os_command,
"bash-completion"]).strip().split()
else:
all_options = only_subcommands
subcommands = [
o for o in all_options if not (o.startswith('-') or o in blacklist)
]
for subcommand in sorted(subcommands):
generate_subcommand(os_command, subcommand, os_file)
print("%d subcommands documented." % len(subcommands))
def generate_subcommands(os_command, os_file, blacklist, only_subcommands,
extra_params, suffix, title_suffix):
"""Convert os_command help subcommands for all subcommands to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
:param blacklist: list of elements that will not be documented
:param only_subcommands: if not empty, list of subcommands to document
:param extra_params: Extra parameter to pass to os_command.
:param suffix: Extra suffix to add to xml:id
:param title_suffix: Extra suffix for title
"""
print("Documenting '%s' subcommands..." % os_command)
blacklist.append("bash-completion")
blacklist.append("complete")
blacklist.append("help")
if not only_subcommands:
args = [os_command]
if extra_params:
args.extend(extra_params)
args.append("bash-completion")
all_options = check_output(args).strip().split()
else:
all_options = only_subcommands
subcommands = [o for o in all_options if not
(o.startswith('-') or o in blacklist)]
for subcommand in sorted(subcommands):
generate_subcommand(os_command, subcommand, os_file, extra_params,
suffix, title_suffix)
print ("%d subcommands documented." % len(subcommands))
def print_gitinfo():
"""Print information about repository and change."""
try:
git_cmd = ["git", "rev-parse", "--abbrev-ref", "HEAD"]
gitbranch = check_output(git_cmd).rstrip()
git_cmd = ["git", "show", "--format=%s", "-s"]
gitsubject = check_output(git_cmd).rstrip()
git_cmd = ["git", "show", "--format=%an", "-s"]
gitauthor = check_output(git_cmd).rstrip()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
print("Testing patch:")
print(" Title: %s" % gitsubject)
print(" Author: %s" % gitauthor)
print(" Branch: %s" % gitbranch)
def print_gitinfo():
"""Print information about repository and change."""
try:
git_cmd = ["git", "rev-parse", "--abbrev-ref", "HEAD"]
gitbranch = check_output(git_cmd).rstrip()
git_cmd = ["git", "show", "--format=%s", "-s"]
gitsubject = check_output(git_cmd).rstrip()
git_cmd = ["git", "show", "--format=%an", "-s"]
gitauthor = check_output(git_cmd).rstrip()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
print("Testing patch:")
print(" Title: %s" % gitsubject)
print(" Author: %s" % gitauthor)
print(" Branch: %s" % gitbranch)
def get_openstack_subcommands(commands):
"""Get all subcommands of 'openstack' without using bashcompletion."""
subcommands = []
for command in commands:
output = check_output(["openstack", "help", command])
for line in output.split("\n"):
if line.strip().startswith(command):
subcommands.append(line.strip())
return subcommands
def get_openstack_subcommands(commands):
"""Get all subcommands of 'openstack' without using bashcompletion."""
subcommands = []
for command in commands:
output = check_output(["openstack", "help", command])
for line in output.split("\n"):
if line.strip().startswith(command):
subcommands.append(line.strip())
return subcommands
def get_gitroot():
"""Return path to top-level of git repository."""
try:
git_args = ["git", "rev-parse", "--show-toplevel"]
gitroot = check_output(git_args).rstrip()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
return gitroot
def get_gitroot():
"""Return path to top-level of git repository."""
try:
git_args = ["git", "rev-parse", "--show-toplevel"]
gitroot = check_output(git_args).rstrip()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
return gitroot
def generate_heading(os_command, api_name, title, os_file):
"""Write DocBook file header.
:param os_command: client command to document
:param api_name: string description of the API of os_command
:param os_file: open filehandle for output of DocBook file
"""
try:
version = check_output([os_command, "--version"],
stderr=subprocess.STDOUT)
except OSError as e:
if e.errno == os.errno.ENOENT:
print("Command %s not found, aborting." % os_command)
sys.exit(1)
# Extract version from "swift 0.3"
version = version.strip().rpartition(' ')[2]
print("Documenting '%s help (version %s)'" % (os_command, version))
if use_help_flag(os_command):
help_str = "<replaceable>COMMAND</replaceable> <option>--help</option>"
else:
help_str = "<option>help</option> <replaceable>COMMAND</replaceable>"
header = """<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<chapter xmlns=\"http://docbook.org/ns/docbook\"
xmlns:xi=\"http://www.w3.org/2001/XInclude\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
version=\"5.0\"
xml:id=\"{0}client_commands\">
<!-- This file is automatically generated, do not edit -->
<?dbhtml stop-chunking?>
<title>{2}</title>
<para>The <command>{0}</command> client is the command-line interface
(CLI) for the {1} and its extensions. This chapter documents
<command>{0}</command> version {3}.
</para>
<para>For help on a specific <command>{0}</command>
command, enter:
</para>
<screen><prompt>$</prompt> <userinput><command>{0}</command> \
{4}</userinput></screen>
<section xml:id=\"{0}client_command_usage\">
<title>{0} usage</title>\n"""
os_file.write(header.format(os_command, api_name, title, version,
help_str))
def generate_heading(os_command, api_name, title, os_file):
"""Write DocBook file header.
:param os_command: client command to document
:param api_name: string description of the API of os_command
:param os_file: open filehandle for output of DocBook file
"""
try:
version = check_output([os_command, "--version"],
stderr=subprocess.STDOUT)
except OSError as e:
if e.errno == os.errno.ENOENT:
print("Command %s not found, aborting." % os_command)
sys.exit(1)
# Extract version from "swift 0.3"
version = version.strip().rpartition(' ')[2]
print("Documenting '%s help (version %s)'" % (os_command, version))
if use_help_flag(os_command):
help_str = "<replaceable>COMMAND</replaceable> <option>--help</option>"
else:
help_str = "<option>help</option> <replaceable>COMMAND</replaceable>"
header = """<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<chapter xmlns=\"http://docbook.org/ns/docbook\"
xmlns:xi=\"http://www.w3.org/2001/XInclude\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
version=\"5.0\"
xml:id=\"{0}client_commands\">
<!-- This file is automatically generated, do not edit -->
<?dbhtml stop-chunking?>
<title>{2}</title>
<para>The <command>{0}</command> client is the command-line interface
(CLI) for the {1} and its extensions. This chapter documents
<command>{0}</command> version {3}.
</para>
<para>For help on a specific <command>{0}</command>
command, enter:
</para>
<screen><prompt>$</prompt> <userinput><command>{0}</command> \
{4}</userinput></screen>
<section xml:id=\"{0}client_command_usage\">
<title>{0} usage</title>\n"""
os_file.write(header.format(os_command, api_name, title, version,
help_str))
def generate_subcommands(os_command, os_file, subcommands, extra_params,
suffix, title_suffix):
"""Convert os_command help subcommands for all subcommands to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
:param subcommands: list or type ('complete' or 'bash-completion')
of subcommands to document
:param extra_params: Extra parameter to pass to os_command.
:param suffix: Extra suffix to add to xml:id
:param title_suffix: Extra suffix for title
"""
print("Documenting '%s' subcommands..." % os_command)
blacklist = ['bash-completion', 'complete', 'help']
if type(subcommands) is str:
args = [os_command]
if extra_params:
args.extend(extra_params)
if subcommands == 'complete':
subcommands = []
args.append('complete')
for line in [x.strip() for x in check_output(args).split('\n')
if x.strip().startswith('cmds_') and '-' in x]:
subcommand, _ = line.split('=')
subcommand = subcommand.replace('cmds_', '').replace('_', ' ')
subcommands.append(subcommand)
else:
args.append('bash-completion')
subcommands = check_output(args).strip().split()
subcommands = sorted([o for o in subcommands if not (o.startswith('-') or
o in blacklist)])
for subcommand in subcommands:
generate_subcommand(os_command, subcommand, os_file, extra_params,
suffix, title_suffix)
print ("%d subcommands documented." % len(subcommands))
def get_modified_files(rootdir, filtering=None):
"""Get modified files below doc directory."""
# There are several tree traversals in this program that do a
# chdir, we need to run this git command always from the rootdir,
# so assure that.
os.chdir(rootdir)
try:
git_args = ["git", "diff", "--name-only", "--relative", "HEAD~1",
"HEAD"]
if filtering is not None:
git_args.append(filtering)
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
return modified_files
def get_modified_files(rootdir, filtering=None):
"""Get modified files below doc directory."""
# There are several tree traversals in this program that do a
# chdir, we need to run this git command always from the rootdir,
# so assure that.
os.chdir(rootdir)
try:
git_args = [
"git", "diff", "--name-only", "--relative", "HEAD~1", "HEAD"
]
if filtering is not None:
git_args.append(filtering)
modified_files = check_output(git_args).strip().split()
except (subprocess.CalledProcessError, OSError) as e:
print("git failed: %s" % e)
sys.exit(1)
return modified_files
def generate_subcommands(os_command, os_file, blacklist, only_subcommands):
"""Convert os_command help subcommands for all subcommands to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
:param blacklist: list of elements that will not be documented
:param only_subcommands: if not empty, list of subcommands to document
"""
print("Documenting '%s' subcommands..." % os_command)
blacklist.append("bash-completion")
blacklist.append("complete")
blacklist.append("help")
if not only_subcommands:
all_options = check_output([os_command,
"bash-completion"]).strip().split()
else:
all_options = only_subcommands
subcommands = [o for o in all_options if not
(o.startswith('-') or o in blacklist)]
for subcommand in sorted(subcommands):
generate_subcommand(os_command, subcommand, os_file)
print ("%d subcommands documented." % len(subcommands))
def generate_subcommand(os_command, os_subcommand, os_file, extra_params,
suffix, title_suffix):
"""Convert os_command help os_subcommand to DocBook.
:param os_command: client command to document
:param os_subcommand: client subcommand to document
:param os_file: open filehandle for output of DocBook file
:param extra_params: Extra parameter to pass to os_command
:param suffix: Extra suffix to add to xml:id
:param title_suffix: Extra suffix for title
"""
print("Documenting subcommand '%s'..." % os_subcommand)
args = [os_command]
if extra_params:
args.extend(extra_params)
if use_help_flag(os_command):
args.append(os_subcommand)
args.append("--help")
else:
args.append("help")
args.append(os_subcommand)
help_lines = check_output(args, stderr=DEVNULL)
if 'positional arguments' in help_lines.lower():
index = help_lines.lower().index('positional arguments')
else:
index = len(help_lines)
if 'deprecated' in (help_lines[0:index].lower()):
print("Subcommand '%s' is deprecated, skipping." % os_subcommand)
return
help_lines = help_lines.split('\n')
os_subcommandid = os_subcommand.replace(' ', '_')
os_file.write(" <section xml:id=\"%sclient_subcommand_%s%s\">\n"
% (os_command, os_subcommandid, suffix))
os_file.write(" <title>%s %s%s</title>\n"
% (os_command, os_subcommand, title_suffix))
if os_command == "swift":
next_line_screen = False
os_file.write("\n <screen><computeroutput>Usage: swift %s"
"</computeroutput></screen>"
% (os_subcommand))
os_file.write("\n <para>")
in_para = True
else:
next_line_screen = True
in_para = False
if extra_params:
extra_paramstr = ' '.join(extra_params)
help_lines[0] = help_lines[0].replace(os_command, "%s %s" %
(os_command, extra_paramstr))
line_index = -1
# Content is:
# usage...
#
# Description
#
# Arguments
skip_lines = False
for line in help_lines:
line_index += 1
if line.startswith('Usage:') and os_command == "swift":
line = line[len("Usage: "):]
if line.startswith(('Arguments:', 'Positional arguments:',
'positional arguments', 'Optional arguments',
'optional arguments')):
if in_para:
in_para = False
os_file.write("\n </para>")
if line.startswith(('Positional arguments',
'positional arguments')):
format_table('Positional arguments',
help_lines[line_index + 1:], os_file)
skip_lines = True
continue
elif line.startswith(('Optional arguments:',
'optional arguments')):
format_table('Optional arguments',
help_lines[line_index + 1:], os_file)
break
else:
format_table('Arguments', help_lines[line_index + 1:], os_file)
break
if skip_lines:
continue
if len(line) == 0:
if not in_para:
os_file.write("</computeroutput></screen>")
os_file.write("\n <para>")
in_para = True
continue
xline = quote_xml(line)
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
else:
os_file.write("\n%s" % (xline))
if in_para:
os_file.write("\n </para>\n")
os_file.write(" </section>\n")
def generate_subcommand(os_command, os_subcommand, os_file):
"""Convert os_command help os_subcommand to DocBook.
:param os_command: client command to document
:param os_subcommand: client subcommand to document
:param os_file: open filehandle for output of DocBook file
"""
if use_help_flag(os_command):
help_lines = check_output([os_command, os_subcommand,
"--help"]).split('\n')
else:
help_lines = check_output([os_command, "help",
os_subcommand]).split('\n')
os_file.write(" <section xml:id=\"%sclient_subcommand_%s\">\n" %
(os_command, os_subcommand))
os_file.write(" <title>%s %s command</title>\n" %
(os_command, os_subcommand))
if os_command == "swift":
next_line_screen = False
os_file.write("\n <screen><computeroutput>Usage: swift %s"
"</computeroutput></screen>" % (os_subcommand))
os_file.write("\n <para>")
in_para = True
else:
next_line_screen = True
in_para = False
line_index = -1
# Content is:
# usage...
#
# Description
#
# Arguments
skip_lines = False
for line in help_lines:
line_index += 1
if line.startswith('Usage:') and os_command == "swift":
line = line[len("Usage: "):]
if line.startswith(
('Arguments:', 'Positional arguments:', 'positional arguments',
'Optional arguments', 'optional arguments')):
if in_para:
in_para = False
os_file.write("\n </para>")
if line.startswith(
('Positional arguments', 'positional arguments')):
format_table('Positional arguments',
help_lines[line_index + 1:], os_file)
skip_lines = True
continue
elif line.startswith(
('Optional arguments:', 'optional arguments')):
format_table('Optional arguments', help_lines[line_index + 1:],
os_file)
break
else:
format_table('Arguments', help_lines[line_index + 1:], os_file)
break
if skip_lines:
continue
if len(line) == 0:
if not in_para:
os_file.write("</computeroutput></screen>")
os_file.write("\n <para>")
in_para = True
continue
xline = quote_xml(line)
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
else:
os_file.write("\n%s" % (xline))
if in_para:
os_file.write("\n </para>\n")
os_file.write(" </section>\n")
def generate_command(os_command, os_file):
"""Convert os_command --help to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
"""
help_lines = check_output([os_command, "--help"]).split('\n')
ignore_next_lines = False
next_line_screen = True
next_line_screen = True
line_index = -1
in_screen = False
for line in help_lines:
line_index += 1
xline = quote_xml(line)
if len(line) > 0 and line[0] != ' ':
# XXX: Might have whitespace before!!
if '<subcommands>' in line:
ignore_next_lines = False
continue
if 'Positional arguments' in line:
ignore_next_lines = True
next_line_screen = True
os_file.write("</computeroutput></screen>\n")
in_screen = False
format_table('Subcommands', help_lines[line_index + 2:],
os_file)
continue
if line.startswith(('Optional arguments:', 'Optional:', 'Options:',
'optional arguments')):
if in_screen:
os_file.write("</computeroutput></screen>\n")
in_screen = False
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_optional\">\n" %
os_command)
os_file.write(
" <title>%s optional arguments</title>\n" %
os_command)
format_table('', help_lines[line_index + 1:], os_file)
next_line_screen = True
ignore_next_lines = True
continue
# neutron
if line.startswith('Commands for API v2.0:'):
if in_screen:
os_file.write("</computeroutput></screen>\n")
in_screen = False
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_api_2_0\">\n" %
os_command)
os_file.write(" <title>%s API v2.0 commands</title>\n" %
os_command)
format_table('', help_lines[line_index + 1:], os_file)
next_line_screen = True
ignore_next_lines = True
continue
# swift
if line.startswith('Examples:'):
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_examples\">\n" %
os_command)
os_file.write(" <title>%s examples</title>\n" %
os_command)
next_line_screen = True
ignore_next_lines = False
continue
if not line.startswith('usage'):
continue
if not ignore_next_lines:
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
in_screen = True
elif len(line) > 0:
os_file.write("\n%s" % xline.rstrip())
if in_screen:
os_file.write("</computeroutput></screen>\n")
os_file.write(" </section>\n")
def generate_heading(os_command, api_name, title, os_file):
"""Write DocBook file header.
:param os_command: client command to document
:param api_name: string description of the API of os_command
:param os_file: open filehandle for output of DocBook file
"""
try:
version = check_output([os_command, "--version"],
stderr=subprocess.STDOUT)
except OSError as e:
if e.errno == os.errno.ENOENT:
print("Command %s not found, aborting." % os_command)
sys.exit(1)
# Extract version from "swift 0.3"
version = version.splitlines()[-1].strip().rpartition(' ')[2]
print("Documenting '%s help (version %s)'" % (os_command, version))
if use_help_flag(os_command):
help_str = "<replaceable>COMMAND</replaceable> <option>--help</option>"
else:
help_str = "<option>help</option> <replaceable>COMMAND</replaceable>"
header1 = """<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<chapter xmlns=\"http://docbook.org/ns/docbook\"
xmlns:xi=\"http://www.w3.org/2001/XInclude\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
version=\"5.0\"
xml:id=\"%(os_command)sclient_commands\">
<!-- This file is automatically generated, do not edit -->
<?dbhtml stop-chunking?>
<title>%(title)s</title>\n"""
if os_command == "openstack":
header2 = """
<para>The <command>%(os_command)s</command> client is a common
OpenStack command-line interface (CLI).\n"""
else:
header2 = """
<para>The <command>%(os_command)s</command> client is the command-line
interface (CLI) for the %(api_name)s and its extensions.\n"""
header3 = """
This chapter documents <command>%(os_command)s</command> version
<literal>%(version)s</literal>.
</para>
<para>For help on a specific <command>%(os_command)s</command>
command, enter:
</para>
<screen><prompt>$</prompt> <userinput><command>%(os_command)s</command> \
%(help_str)s</userinput></screen>
<section xml:id=\"%(os_command)sclient_command_usage\">
<title>%(os_command)s usage</title>\n"""
if os_command == "keystone":
header_deprecation = """
<warning>
<para>The %(os_command)s CLI is deprecated in favor of
python-openstackclient. For a Python library, continue using
python-%(os_command)sclient.</para>
</warning>\n"""
else:
header_deprecation = None
format_dict = {
"os_command": os_command,
"api_name": api_name,
"title": title,
"version": version,
"help_str": help_str
}
os_file.write(header1 % format_dict)
if header_deprecation:
os_file.write(header_deprecation % format_dict)
os_file.write(header2 % format_dict)
os_file.write(header3 % format_dict)
def generate_subcommand(os_command, os_subcommand, os_file, extra_params,
suffix, title_suffix):
"""Convert os_command help os_subcommand to DocBook.
:param os_command: client command to document
:param os_subcommand: client subcommand to document
:param os_file: open filehandle for output of DocBook file
:param extra_params: Extra parameter to pass to os_command
:param suffix: Extra suffix to add to xml:id
:param title_suffix: Extra suffix for title
"""
args = [os_command]
if extra_params:
args.extend(extra_params)
if use_help_flag(os_command):
args.append(os_subcommand)
args.append("--help")
else:
args.append("help")
args.append(os_subcommand)
help_lines = check_output(args).split('\n')
os_subcommandid = os_subcommand.replace(' ', '_')
os_file.write(" <section xml:id=\"%sclient_subcommand_%s%s\">\n" %
(os_command, os_subcommandid, suffix))
os_file.write(" <title>%s %s%s</title>\n" %
(os_command, os_subcommand, title_suffix))
if os_command == "swift":
next_line_screen = False
os_file.write("\n <screen><computeroutput>Usage: swift %s"
"</computeroutput></screen>" % (os_subcommand))
os_file.write("\n <para>")
in_para = True
else:
next_line_screen = True
in_para = False
if extra_params:
extra_paramstr = ' '.join(extra_params)
help_lines[0] = help_lines[0].replace(
os_command, "%s %s" % (os_command, extra_paramstr))
line_index = -1
# Content is:
# usage...
#
# Description
#
# Arguments
skip_lines = False
for line in help_lines:
line_index += 1
if line.startswith('Usage:') and os_command == "swift":
line = line[len("Usage: "):]
if line.startswith(
('Arguments:', 'Positional arguments:', 'positional arguments',
'Optional arguments', 'optional arguments')):
if in_para:
in_para = False
os_file.write("\n </para>")
if line.startswith(
('Positional arguments', 'positional arguments')):
format_table('Positional arguments',
help_lines[line_index + 1:], os_file)
skip_lines = True
continue
elif line.startswith(
('Optional arguments:', 'optional arguments')):
format_table('Optional arguments', help_lines[line_index + 1:],
os_file)
break
else:
format_table('Arguments', help_lines[line_index + 1:], os_file)
break
if skip_lines:
continue
if len(line) == 0:
if not in_para:
os_file.write("</computeroutput></screen>")
os_file.write("\n <para>")
in_para = True
continue
xline = quote_xml(line)
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
else:
os_file.write("\n%s" % (xline))
if in_para:
os_file.write("\n </para>\n")
os_file.write(" </section>\n")
def generate_subcommand(os_command, os_subcommand, os_file):
"""Convert os_command help os_subcommand to DocBook.
:param os_command: client command to document
:param os_subcommand: client subcommand to document
:param os_file: open filehandle for output of DocBook file
"""
if os_command == "swift":
help_lines = check_output([os_command, os_subcommand,
"--help"]).split('\n')
else:
help_lines = check_output([os_command, "help",
os_subcommand]).split('\n')
os_file.write(" <section xml:id=\"%sclient_subcommand_%s\">\n"
% (os_command, os_subcommand))
os_file.write(" <title>%s %s command</title>\n"
% (os_command, os_subcommand))
if os_command == "swift":
next_line_screen = False
os_file.write("\n <screen><computeroutput>Usage: swift %s"
"</computeroutput></screen>"
% (os_subcommand))
os_file.write("\n <para>")
in_para = True
else:
next_line_screen = True
in_para = False
line_index = -1
# Content is:
# usage...
#
# Description
#
# Arguments
skip_lines = False
for line in help_lines:
line_index += 1
if line.startswith('Usage:') and os_command == "swift":
line = line[len("Usage: "):]
if line.startswith(('Arguments:', 'Positional arguments:',
'positional arguments', 'Optional arguments',
'optional arguments')):
if in_para:
in_para = False
os_file.write("\n </para>")
if line.startswith(('Positional arguments',
'positional arguments')):
format_table('Positional arguments',
help_lines[line_index + 1:], os_file)
skip_lines = True
continue
elif line.startswith(('Optional arguments:',
'optional arguments')):
format_table('Optional arguments',
help_lines[line_index + 1:], os_file)
break
else:
format_table('Arguments', help_lines[line_index + 1:], os_file)
break
if skip_lines:
continue
if len(line) == 0:
if not in_para:
os_file.write("</computeroutput></screen>")
os_file.write("\n <para>")
in_para = True
continue
xline = quote_xml(line)
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
else:
os_file.write("\n%s" % (xline))
if in_para:
os_file.write("\n </para>\n")
os_file.write(" </section>\n")
def generate_command(os_command, os_file):
"""Convert os_command --help to DocBook.
:param os_command: client command to document
:param os_file: open filehandle for output of DocBook file
"""
help_lines = check_output([os_command, "--help"]).split('\n')
ignore_next_lines = False
next_line_screen = True
next_line_screen = True
line_index = -1
in_screen = False
for line in help_lines:
line_index += 1
xline = quote_xml(line)
if len(line) > 0 and line[0] != ' ':
# XXX: Might have whitespace before!!
if '<subcommands>' in line:
ignore_next_lines = False
continue
if 'Positional arguments' in line:
ignore_next_lines = True
next_line_screen = True
os_file.write("</computeroutput></screen>\n")
in_screen = False
format_table('Subcommands', help_lines[line_index + 2:],
os_file)
continue
if line.startswith(('Optional arguments:', 'Optional:',
'Options:', 'optional arguments')):
if in_screen:
os_file.write("</computeroutput></screen>\n")
in_screen = False
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_optional\">\n"
% os_command)
os_file.write(" <title>%s optional arguments</title>\n"
% os_command)
format_table('', help_lines[line_index + 1:],
os_file)
next_line_screen = True
ignore_next_lines = True
continue
# neutron
if line.startswith('Commands for API v2.0:'):
if in_screen:
os_file.write("</computeroutput></screen>\n")
in_screen = False
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_api_2_0\">\n"
% os_command)
os_file.write(" <title>%s API v2.0 commands</title>\n"
% os_command)
format_table('', help_lines[line_index + 1:],
os_file)
next_line_screen = True
ignore_next_lines = True
continue
# swift
if line.startswith('Examples:'):
os_file.write(" </section>\n")
os_file.write(" <section ")
os_file.write("xml:id=\"%sclient_command_examples\">\n"
% os_command)
os_file.write(" <title>%s examples</title>\n"
% os_command)
next_line_screen = True
ignore_next_lines = False
continue
if not line.startswith('usage'):
continue
if not ignore_next_lines:
if next_line_screen:
os_file.write(" <screen><computeroutput>%s" % xline)
next_line_screen = False
in_screen = True
elif len(line) > 0:
os_file.write("\n%s" % (xline))
if in_screen:
os_file.write("</computeroutput></screen>\n")
os_file.write(" </section>\n")