diff options
Diffstat (limited to 'doc/guides/conf.py')
| -rw-r--r-- | doc/guides/conf.py | 140 |
1 files changed, 113 insertions, 27 deletions
diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 149bcdbc..c3cd0bd6 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -58,11 +58,15 @@ html_add_permalinks = "" html_show_copyright = False highlight_language = 'none' -version = subprocess.check_output(['make', '-sRrC', '../../', 'showversion']).decode('utf-8').rstrip() +version = subprocess.check_output(['make', '-sRrC', '../../', 'showversion']) +version = version.decode('utf-8').rstrip() release = version master_doc = 'index' +# Maximum feature description string length +feature_str_len = 25 + # Figures, tables and code-blocks automatically numbered if they have caption numfig = True @@ -75,7 +79,7 @@ latex_documents = [ ] # Latex directives to be included directly in the latex/pdf docs. -latex_preamble = r""" +custom_latex_preamble = r""" \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{helvet} @@ -91,9 +95,10 @@ latex_elements = { 'classoptions': ',openany,oneside', 'babel': '\\usepackage[english]{babel}', # customize Latex formatting - 'preamble': latex_preamble + 'preamble': custom_latex_preamble } + # Override the default Latex formatter in order to modify the # code/verbatim blocks. class CustomLatexFormatter(LatexFormatter): @@ -117,12 +122,12 @@ man_pages = [("testpmd_app_ug/run_app", "testpmd", ("tools/devbind", "dpdk-devbind", "check device status and bind/unbind them from drivers", "", 8)] -######## :numref: fallback ######## + +# ####### :numref: fallback ######## # The following hook functions add some simple handling for the :numref: # directive for Sphinx versions prior to 1.3.1. The functions replace the # :numref: reference with a link to the target (for all Sphinx doc types). # It doesn't try to label figures/tables. - def numref_role(reftype, rawtext, text, lineno, inliner): """ Add a Sphinx role to handle numref references. Note, we can't convert @@ -136,6 +141,7 @@ def numref_role(reftype, rawtext, text, lineno, inliner): internal=True) return [newnode], [] + def process_numref(app, doctree, from_docname): """ Process the numref nodes once the doctree has been built and prior to @@ -172,25 +178,24 @@ def process_numref(app, doctree, from_docname): node.replace_self(newnode) -def generate_nic_overview_table(output_filename): +def generate_overview_table(output_filename, table_id, section, table_name, title): """ - Function to generate the NIC Overview Table from the ini files that define - the features for each NIC. + Function to generate the Overview Table from the ini files that define + the features for each driver. The default features for the table and their order is defined by the 'default.ini' file. """ - # Default worning string. - warning = 'Warning generate_nic_overview_table()' + # Default warning string. + warning = 'Warning generate_overview_table()' # Get the default features and order from the 'default.ini' file. ini_path = path_join(dirname(output_filename), 'features') config = configparser.ConfigParser() config.optionxform = str config.read(path_join(ini_path, 'default.ini')) - default_section = 'Features' - default_features = config.items(default_section) + default_features = config.items(section) # Create a dict of the valid features to validate the other ini files. valid_features = {} @@ -200,7 +205,7 @@ def generate_nic_overview_table(output_filename): valid_features[key] = ' ' max_feature_length = max(max_feature_length, len(key)) - # Get a list of NIC ini files, excluding 'default.ini'. + # Get a list of driver ini files, excluding 'default.ini'. ini_files = [basename(file) for file in listdir(ini_path) if file.endswith('.ini') and file != 'default.ini'] ini_files.sort() @@ -220,7 +225,7 @@ def generate_nic_overview_table(output_filename): header_names.append(name) - # Create a dict of the defined features for each NIC from the ini files. + # Create a dict of the defined features for each driver from the ini files. ini_data = {} for ini_filename in ini_files: config = configparser.ConfigParser() @@ -231,14 +236,14 @@ def generate_nic_overview_table(output_filename): ini_data[ini_filename] = valid_features.copy() # Check for a valid ini section. - if not config.has_section(default_section): + if not config.has_section(section): print("{}: File '{}' has no [{}] secton".format(warning, ini_filename, - default_section)) + section)) continue # Check for valid features names. - for name, value in config.items(default_section): + for name, value in config.items(section): if name not in valid_features: print("{}: Unknown feature '{}' in '{}'".format(warning, name, @@ -249,18 +254,17 @@ def generate_nic_overview_table(output_filename): # Get the first letter only. ini_data[ini_filename][name] = value[0] - # Print out the RST NIC Overview table from the ini file data. + # Print out the RST Driver Overview table from the ini file data. outfile = open(output_filename, 'w') num_cols = len(header_names) - print('.. table:: Features availability in networking drivers\n', - file=outfile) - - print_table_header(outfile, num_cols, header_names) + print_table_css(outfile, table_id) + print('.. table:: ' + table_name + '\n', file=outfile) + print_table_header(outfile, num_cols, header_names, title) print_table_body(outfile, num_cols, ini_files, ini_data, default_features) -def print_table_header(outfile, num_cols, header_names): +def print_table_header(outfile, num_cols, header_names, title): """ Print the RST table header. The header names are vertical. """ print_table_divider(outfile, num_cols) @@ -268,7 +272,7 @@ def print_table_header(outfile, num_cols, header_names): for name in header_names: line += ' ' + name[0] - print_table_row(outfile, 'Feature', line) + print_table_row(outfile, title, line) for i in range(1, 10): line = '' @@ -297,7 +301,7 @@ def print_table_body(outfile, num_cols, ini_files, ini_data, default_features): def print_table_row(outfile, feature, line): """ Print a single row of the table with fixed formatting. """ line = line.rstrip() - print(' {:<20}{}'.format(feature, line), file=outfile) + print(' {:<{}}{}'.format(feature, feature_str_len, line), file=outfile) def print_table_divider(outfile, num_cols): @@ -306,13 +310,95 @@ def print_table_divider(outfile, num_cols): column_dividers = ['='] * num_cols line += ' '.join(column_dividers) - feature = '=' * 20 + feature = '=' * feature_str_len print_table_row(outfile, feature, line) +def print_table_css(outfile, table_id): + template = """ +.. raw:: html + + <style> + .wy-nav-content { + opacity: .99; + } + table#idx { + cursor: default; + overflow: hidden; + } + table#idx th, table#idx td { + text-align: center; + } + table#idx th { + font-size: 80%; + white-space: pre-wrap; + vertical-align: top; + padding: 2px; + } + table#idx th:first-child { + vertical-align: bottom; + } + table#idx td { + font-size: 70%; + padding: 1px; + } + table#idx td:first-child { + padding-left: 1em; + text-align: left; + } + table#idx tr:nth-child(2n-1) td { + background-color: rgba(210, 210, 210, 0.2); + } + table#idx th:not(:first-child):hover, + table#idx td:not(:first-child):hover { + position: relative; + } + table#idx th:not(:first-child):hover::after, + table#idx td:not(:first-child):hover::after { + content: ''; + height: 6000px; + top: -3000px; + width: 100%; + left: 0; + position: absolute; + z-index: -1; + background-color: #ffb; + } + table#idx tr:hover td { + background-color: #ffb; + } + </style> +""" + print(template.replace("idx", "id%d" % (table_id)), file=outfile) + + def setup(app): - generate_nic_overview_table('doc/guides/nics/overview_table.txt') + table_file = dirname(__file__) + '/nics/overview_table.txt' + generate_overview_table(table_file, 1, + 'Features', + 'Features availability in networking drivers', + 'Feature') + table_file = dirname(__file__) + '/cryptodevs/overview_feature_table.txt' + generate_overview_table(table_file, 1, + 'Features', + 'Features availability in crypto drivers', + 'Feature') + table_file = dirname(__file__) + '/cryptodevs/overview_cipher_table.txt' + generate_overview_table(table_file, 2, + 'Cipher', + 'Cipher algorithms in crypto drivers', + 'Cipher algorithm') + table_file = dirname(__file__) + '/cryptodevs/overview_auth_table.txt' + generate_overview_table(table_file, 3, + 'Auth', + 'Authentication algorithms in crypto drivers', + 'Authentication algorithm') + table_file = dirname(__file__) + '/cryptodevs/overview_aead_table.txt' + generate_overview_table(table_file, 4, + 'AEAD', + 'AEAD algorithms in crypto drivers', + 'AEAD algorithm') if LooseVersion(sphinx_version) < LooseVersion('1.3.1'): print('Upgrade sphinx to version >= 1.3.1 for ' |