-# BSD LICENSE
-# Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# * Redistributions of source code must retain the above copyright
-# notice, this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright
-# notice, this list of conditions and the following disclaimer in
-# the documentation and/or other materials provided with the
-# distribution.
-# * Neither the name of Intel Corporation nor the names of its
-# contributors may be used to endorse or promote products derived
-# from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2010-2015 Intel Corporation
from __future__ import print_function
import subprocess
# Python 3.
import configparser
+try:
+ import sphinx_rtd_theme
-project = 'Data Plane Development Kit'
-
-if LooseVersion(sphinx_version) >= LooseVersion('1.3.1'):
html_theme = "sphinx_rtd_theme"
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+except:
+ print('Install the sphinx ReadTheDocs theme for improved html documentation '
+ 'layout: pip install sphinx_rtd_theme')
+ pass
+
+project = 'Data Plane Development Kit'
html_logo = '../logo/DPDK_logo_vertical_rev_small.png'
latex_logo = '../logo/DPDK_logo_horizontal_tag.png'
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
]
# 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}
'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):
("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
internal=True)
return [newnode], []
+
def process_numref(app, doctree, from_docname):
"""
Process the numref nodes once the doctree has been built and prior to
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 = {}
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()
# Build up a list of the table header names from the ini filenames.
- header_names = []
+ pmd_names = []
for ini_filename in ini_files:
name = ini_filename[:-4]
name = name.replace('_vf', 'vf')
+ pmd_names.append(name)
- # Pad the table header names to match the existing format.
+ # Pad the table header names.
+ max_header_len = len(max(pmd_names, key=len))
+ header_names = []
+ for name in pmd_names:
if '_vec' in name:
pmd, vec = name.split('_')
- name = '{0:{fill}{align}7}vec'.format(pmd, fill='.', align='<')
+ name = '{0:{fill}{align}{width}}vec'.format(pmd,
+ fill='.', align='<', width=max_header_len-3)
else:
- name = '{0:{fill}{align}10}'.format(name, fill=' ', align='<')
-
+ name = '{0:{fill}{align}{width}}'.format(name,
+ fill=' ', align='<', width=max_header_len)
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()
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,
# 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)
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):
+ for i in range(1, len(header_names[0])):
line = ''
for name in header_names:
line += ' ' + name[i]
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):
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: 72%;
+ white-space: pre-wrap;
+ vertical-align: top;
+ padding: 0.5em 0;
+ min-width: 0.9em;
+ width: 2em;
+ }
+ table#idx col:first-child {
+ width: 0;
+ }
+ 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')
+ table_file = dirname(__file__) + '/compressdevs/overview_feature_table.txt'
+ generate_overview_table(table_file, 1,
+ 'Features',
+ 'Features availability in compression drivers',
+ 'Feature')
if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
print('Upgrade sphinx to version >= 1.3.1 for '
app.add_role('numref', numref_role)
# Process the numref references once the doctree has been created.
app.connect('doctree-resolved', process_numref)
+
+ app.add_stylesheet('css/custom.css')
Code Review / deb_dpdk.git / blobdiff