mirror of
https://github.com/borgbackup/borg.git
synced 2025-03-03 10:17:40 +00:00
docs: uniform tables for listing options (HTML only)
This commit is contained in:
Marian Beermann
parent
8cc3e527a2
commit
e76fae0545
2 changed files with 122 additions and 8 deletions
|
|
@ -119,17 +119,34 @@ table.docutils:not(.footnote) tr:last-child td {
|
|||
}
|
||||
|
||||
table.docutils:not(.footnote) tr td:first-child,
|
||||
table.docutils:not(.footnote) tr th:first-child,
|
||||
table.docutils.option-list tr td {
|
||||
table.docutils:not(.footnote) tr th:first-child {
|
||||
border-left: 0;
|
||||
}
|
||||
|
||||
table.docutils:not(.footnote) tr td:last-child,
|
||||
table.docutils:not(.footnote) tr th:last-child,
|
||||
table.docutils.option-list tr td {
|
||||
table.docutils.borg-options-table tr td {
|
||||
border-right: 0;
|
||||
}
|
||||
|
||||
table.docutils.borg-options-table tr td {
|
||||
border-left: 0;
|
||||
border-right: 0;
|
||||
}
|
||||
|
||||
table.docutils.borg-options-table tr td:first-child:not([colspan="3"]) {
|
||||
border-top: 0;
|
||||
border-bottom: 0;
|
||||
}
|
||||
|
||||
.borg-options-table td[colspan="3"] p {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.borg-options-table {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
kbd, /* used in usage pages for options */
|
||||
code,
|
||||
.rst-content tt.literal,
|
||||
|
|
@ -153,12 +170,12 @@ kbd {
|
|||
font-family: Consolas, monospace;
|
||||
}
|
||||
|
||||
kbd .option {
|
||||
.borg-options-table tr td:nth-child(2) .pre {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
table.docutils.option-list td.option-group {
|
||||
min-width: 10em;
|
||||
.borg-options-table tr td:first-child {
|
||||
width: 2em;
|
||||
}
|
||||
|
||||
cite {
|
||||
|
|
|
|||
101
setup.py
101
setup.py
|
|
@ -288,11 +288,108 @@ def write_usage(self, parser, fp):
|
|||
fp.write('\n\n')
|
||||
|
||||
def write_options(self, parser, fp):
|
||||
def is_positional_group(group):
|
||||
return any(not o.option_strings for o in group._group_actions)
|
||||
|
||||
# HTML output:
|
||||
# A table using some column-spans
|
||||
|
||||
def html_write(s):
|
||||
for line in s.splitlines():
|
||||
fp.write(' ' + line + '\n')
|
||||
|
||||
rows = []
|
||||
for group in parser._action_groups:
|
||||
if group.title == 'Common options':
|
||||
fp.write('\n\n.. class:: borg-common-opt-ref\n\n:ref:`common_options`\n')
|
||||
# (no of columns used, columns, ...)
|
||||
rows.append((1, '.. class:: borg-common-opt-ref\n\n:ref:`common_options`'))
|
||||
else:
|
||||
self.write_options_group(group, fp)
|
||||
rows.append((1, '**%s**' % group.title))
|
||||
if is_positional_group(group):
|
||||
for option in group._group_actions:
|
||||
rows.append((3, '', '``%s``' % option.metavar, option.help or ''))
|
||||
else:
|
||||
for option in group._group_actions:
|
||||
if option.metavar:
|
||||
option_fmt = '``%s ' + option.metavar + '``'
|
||||
else:
|
||||
option_fmt = '``%s``'
|
||||
option_str = ', '.join(option_fmt % s for s in option.option_strings)
|
||||
option_desc = textwrap.dedent((option.help or '') % option.__dict__)
|
||||
rows.append((3, '', option_str, option_desc))
|
||||
|
||||
fp.write('.. only:: html\n\n')
|
||||
table = io.StringIO()
|
||||
table.write('.. class:: borg-options-table\n\n')
|
||||
self.rows_to_table(rows, table.write)
|
||||
fp.write(textwrap.indent(table.getvalue(), ' ' * 4))
|
||||
|
||||
# LaTeX output:
|
||||
# Regular rST option lists (irregular column widths)
|
||||
latex_options = io.StringIO()
|
||||
for group in parser._action_groups:
|
||||
if group.title == 'Common options':
|
||||
latex_options.write('\n\n:ref:`common_options`\n')
|
||||
latex_options.write(' |')
|
||||
else:
|
||||
self.write_options_group(group, latex_options)
|
||||
fp.write('\n.. only:: latex\n\n')
|
||||
fp.write(textwrap.indent(latex_options.getvalue(), ' ' * 4))
|
||||
|
||||
def rows_to_table(self, rows, write):
|
||||
def write_row_separator():
|
||||
write('+')
|
||||
for column_width in column_widths:
|
||||
write('-' * (column_width + 1))
|
||||
write('+')
|
||||
write('\n')
|
||||
|
||||
# Find column count and width
|
||||
column_count = max(columns for columns, *_ in rows)
|
||||
column_widths = [0] * column_count
|
||||
for columns, *cells in rows:
|
||||
for i in range(columns):
|
||||
# "+ 1" because we want a space between the cell contents and the delimiting "|" in the output
|
||||
column_widths[i] = max(column_widths[i], len(cells[i]) + 1)
|
||||
|
||||
for columns, *cells in rows:
|
||||
write_row_separator()
|
||||
# If a cell contains newlines, then the row must be split up in individual rows
|
||||
# where each cell contains no newline.
|
||||
rowspanning_cells = []
|
||||
original_cells = list(cells)
|
||||
while any('\n' in cell for cell in original_cells):
|
||||
cell_bloc = []
|
||||
for i, cell in enumerate(original_cells):
|
||||
pre, _, original_cells[i] = cell.partition('\n')
|
||||
cell_bloc.append(pre)
|
||||
rowspanning_cells.append(cell_bloc)
|
||||
rowspanning_cells.append(original_cells)
|
||||
for cells in rowspanning_cells:
|
||||
for i, column_width in enumerate(column_widths):
|
||||
if i < columns:
|
||||
write('| ')
|
||||
write(cells[i].ljust(column_width))
|
||||
else:
|
||||
write(' ')
|
||||
write(''.ljust(column_width))
|
||||
write('|\n')
|
||||
|
||||
write_row_separator()
|
||||
# This bit of JavaScript kills the <colgroup> that is invariably inserted by docutils,
|
||||
# but does absolutely no good here. It sets bogus column widths which cannot be overridden
|
||||
# with CSS alone.
|
||||
# Since this is HTML-only output, it would be possible to just generate a <table> directly,
|
||||
# but then we'd lose rST formatting.
|
||||
write(textwrap.dedent("""
|
||||
.. raw:: html
|
||||
|
||||
<script type='text/javascript'>
|
||||
$(window).load(function () {
|
||||
$('.borg-options-table colgroup').remove();
|
||||
})
|
||||
</script>
|
||||
"""))
|
||||
|
||||
def write_options_group(self, group, fp, with_title=True, base_indent=4):
|
||||
def is_positional_group(group):
|
||||
|
|
|
|||
Loading…
Reference in a new issue