doc/guides/conf.py

   1 #   BSD LICENSE
   2 #   Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
   3 #   All rights reserved.
   4 #
   5 #   Redistribution and use in source and binary forms, with or without
   6 #   modification, are permitted provided that the following conditions
   7 #   are met:
   8 #
   9 #   * Redistributions of source code must retain the above copyright
  10 #   notice, this list of conditions and the following disclaimer.
  11 #   * Redistributions in binary form must reproduce the above copyright
  12 #   notice, this list of conditions and the following disclaimer in
  13 #   the documentation and/or other materials provided with the
  14 #   distribution.
  15 #   * Neither the name of Intel Corporation nor the names of its
  16 #   contributors may be used to endorse or promote products derived
  17 #   from this software without specific prior written permission.
  18 #
  19 #   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 #   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 #   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 #   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 #   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 #   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 #   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 #   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 #   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 #   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 #   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 from __future__ import print_function
  32 import subprocess
  33 from docutils import nodes
  34 from distutils.version import LooseVersion
  35 from sphinx import __version__ as sphinx_version
  36 from sphinx.highlighting import PygmentsBridge
  37 from pygments.formatters.latex import LatexFormatter
  38 from os import listdir
  39 from os.path import basename
  40 from os.path import dirname
  41 from os.path import join as path_join
  42
  43 try:
  44     # Python 2.
  45     import ConfigParser as configparser
  46 except:
  47     # Python 3.
  48     import configparser
  49
  50
  51 project = 'Data Plane Development Kit'
  52
  53 if LooseVersion(sphinx_version) >= LooseVersion('1.3.1'):
  54     html_theme = "sphinx_rtd_theme"
  55 html_logo = '../logo/DPDK_logo_vertical_rev_small.png'
  56 latex_logo = '../logo/DPDK_logo_horizontal_tag.png'
  57 html_add_permalinks = ""
  58 html_show_copyright = False
  59 highlight_language = 'none'
  60
  61 version = subprocess.check_output(['make', '-sRrC', '../../', 'showversion'])
  62 version = version.decode('utf-8').rstrip()
  63 release = version
  64
  65 master_doc = 'index'
  66
  67 # Maximum feature description string length
  68 feature_str_len = 25
  69
  70 # Figures, tables and code-blocks automatically numbered if they have caption
  71 numfig = True
  72
  73 latex_documents = [
  74     ('index',
  75      'doc.tex',
  76      '',
  77      '',
  78      'manual')
  79 ]
  80
  81 # Latex directives to be included directly in the latex/pdf docs.
  82 latex_preamble = r"""
  83 \usepackage[utf8]{inputenc}
  84 \usepackage[T1]{fontenc}
  85 \usepackage{helvet}
  86 \renewcommand{\familydefault}{\sfdefault}
  87 \RecustomVerbatimEnvironment{Verbatim}{Verbatim}{xleftmargin=5mm}
  88 """
  89
  90 # Configuration for the latex/pdf docs.
  91 latex_elements = {
  92     'papersize': 'a4paper',
  93     'pointsize': '11pt',
  94     # remove blank pages
  95     'classoptions': ',openany,oneside',
  96     'babel': '\\usepackage[english]{babel}',
  97     # customize Latex formatting
  98     'preamble': latex_preamble
  99 }
 100
 101
 102 # Override the default Latex formatter in order to modify the
 103 # code/verbatim blocks.
 104 class CustomLatexFormatter(LatexFormatter):
 105     def __init__(self, **options):
 106         super(CustomLatexFormatter, self).__init__(**options)
 107         # Use the second smallest font size for code/verbatim blocks.
 108         self.verboptions = r'formatcom=\footnotesize'
 109
 110 # Replace the default latex formatter.
 111 PygmentsBridge.latex_formatter = CustomLatexFormatter
 112
 113 # Configuration for man pages
 114 man_pages = [("testpmd_app_ug/run_app", "testpmd",
 115               "tests for dpdk pmds", "", 1),
 116              ("tools/pdump", "dpdk-pdump",
 117               "enable packet capture on dpdk ports", "", 1),
 118              ("tools/proc_info", "dpdk-procinfo",
 119               "access dpdk port stats and memory info", "", 1),
 120              ("tools/pmdinfo", "dpdk-pmdinfo",
 121               "dump a PMDs hardware support info", "", 1),
 122              ("tools/devbind", "dpdk-devbind",
 123               "check device status and bind/unbind them from drivers", "", 8)]
 124
 125
 126 # ####### :numref: fallback ########
 127 # The following hook functions add some simple handling for the :numref:
 128 # directive for Sphinx versions prior to 1.3.1. The functions replace the
 129 # :numref: reference with a link to the target (for all Sphinx doc types).
 130 # It doesn't try to label figures/tables.
 131 def numref_role(reftype, rawtext, text, lineno, inliner):
 132     """
 133     Add a Sphinx role to handle numref references. Note, we can't convert
 134     the link here because the doctree isn't build and the target information
 135     isn't available.
 136     """
 137     # Add an identifier to distinguish numref from other references.
 138     newnode = nodes.reference('',
 139                               '',
 140                               refuri='_local_numref_#%s' % text,
 141                               internal=True)
 142     return [newnode], []
 143
 144
 145 def process_numref(app, doctree, from_docname):
 146     """
 147     Process the numref nodes once the doctree has been built and prior to
 148     writing the files. The processing involves replacing the numref with a
 149     link plus text to indicate if it is a Figure or Table link.
 150     """
 151
 152     # Iterate over the reference nodes in the doctree.
 153     for node in doctree.traverse(nodes.reference):
 154         target = node.get('refuri', '')
 155
 156         # Look for numref nodes.
 157         if target.startswith('_local_numref_#'):
 158             target = target.replace('_local_numref_#', '')
 159
 160             # Get the target label and link information from the Sphinx env.
 161             data = app.builder.env.domains['std'].data
 162             docname, label, _ = data['labels'].get(target, ('', '', ''))
 163             relative_url = app.builder.get_relative_uri(from_docname, docname)
 164
 165             # Add a text label to the link.
 166             if target.startswith('figure'):
 167                 caption = 'Figure'
 168             elif target.startswith('table'):
 169                 caption = 'Table'
 170             else:
 171                 caption = 'Link'
 172
 173             # New reference node with the updated link information.
 174             newnode = nodes.reference('',
 175                                       caption,
 176                                       refuri='%s#%s' % (relative_url, label),
 177                                       internal=True)
 178             node.replace_self(newnode)
 179
 180
 181 def generate_nic_overview_table(output_filename):
 182     """
 183     Function to generate the NIC Overview Table from the ini files that define
 184     the features for each NIC.
 185
 186     The default features for the table and their order is defined by the
 187     'default.ini' file.
 188
 189     """
 190     # Default worning string.
 191     warning = 'Warning generate_nic_overview_table()'
 192
 193     # Get the default features and order from the 'default.ini' file.
 194     ini_path = path_join(dirname(output_filename), 'features')
 195     config = configparser.ConfigParser()
 196     config.optionxform = str
 197     config.read(path_join(ini_path, 'default.ini'))
 198     default_section = 'Features'
 199     default_features = config.items(default_section)
 200
 201     # Create a dict of the valid features to validate the other ini files.
 202     valid_features = {}
 203     max_feature_length = 0
 204     for feature in default_features:
 205         key = feature[0]
 206         valid_features[key] = ' '
 207         max_feature_length = max(max_feature_length, len(key))
 208
 209     # Get a list of NIC ini files, excluding 'default.ini'.
 210     ini_files = [basename(file) for file in listdir(ini_path)
 211                  if file.endswith('.ini') and file != 'default.ini']
 212     ini_files.sort()
 213
 214     # Build up a list of the table header names from the ini filenames.
 215     header_names = []
 216     for ini_filename in ini_files:
 217         name = ini_filename[:-4]
 218         name = name.replace('_vf', 'vf')
 219
 220         # Pad the table header names to match the existing format.
 221         if '_vec' in name:
 222             pmd, vec = name.split('_')
 223             name = '{0:{fill}{align}7}vec'.format(pmd, fill='.', align='<')
 224         else:
 225             name = '{0:{fill}{align}10}'.format(name, fill=' ', align='<')
 226
 227         header_names.append(name)
 228
 229     # Create a dict of the defined features for each NIC from the ini files.
 230     ini_data = {}
 231     for ini_filename in ini_files:
 232         config = configparser.ConfigParser()
 233         config.optionxform = str
 234         config.read(path_join(ini_path, ini_filename))
 235
 236         # Initialize the dict with the default.ini value.
 237         ini_data[ini_filename] = valid_features.copy()
 238
 239         # Check for a valid ini section.
 240         if not config.has_section(default_section):
 241             print("{}: File '{}' has no [{}] secton".format(warning,
 242                                                             ini_filename,
 243                                                             default_section))
 244             continue
 245
 246         # Check for valid features names.
 247         for name, value in config.items(default_section):
 248             if name not in valid_features:
 249                 print("{}: Unknown feature '{}' in '{}'".format(warning,
 250                                                                 name,
 251                                                                 ini_filename))
 252                 continue
 253
 254             if value is not '':
 255                 # Get the first letter only.
 256                 ini_data[ini_filename][name] = value[0]
 257
 258     # Print out the RST NIC Overview table from the ini file data.
 259     outfile = open(output_filename, 'w')
 260     num_cols = len(header_names)
 261
 262     print('.. table:: Features availability in networking drivers\n',
 263           file=outfile)
 264
 265     print_table_header(outfile, num_cols, header_names)
 266     print_table_body(outfile, num_cols, ini_files, ini_data, default_features)
 267
 268
 269 def print_table_header(outfile, num_cols, header_names):
 270     """ Print the RST table header. The header names are vertical. """
 271     print_table_divider(outfile, num_cols)
 272
 273     line = ''
 274     for name in header_names:
 275         line += ' ' + name[0]
 276
 277     print_table_row(outfile, 'Feature', line)
 278
 279     for i in range(1, 10):
 280         line = ''
 281         for name in header_names:
 282             line += ' ' + name[i]
 283
 284         print_table_row(outfile, '', line)
 285
 286     print_table_divider(outfile, num_cols)
 287
 288
 289 def print_table_body(outfile, num_cols, ini_files, ini_data, default_features):
 290     """ Print out the body of the table. Each row is a NIC feature. """
 291
 292     for feature, _ in default_features:
 293         line = ''
 294
 295         for ini_filename in ini_files:
 296             line += ' ' + ini_data[ini_filename][feature]
 297
 298         print_table_row(outfile, feature, line)
 299
 300     print_table_divider(outfile, num_cols)
 301
 302
 303 def print_table_row(outfile, feature, line):
 304     """ Print a single row of the table with fixed formatting. """
 305     line = line.rstrip()
 306     print('   {:<{}}{}'.format(feature, feature_str_len, line), file=outfile)
 307
 308
 309 def print_table_divider(outfile, num_cols):
 310     """ Print the table divider line. """
 311     line = ' '
 312     column_dividers = ['='] * num_cols
 313     line += ' '.join(column_dividers)
 314
 315     feature = '=' * feature_str_len
 316
 317     print_table_row(outfile, feature, line)
 318
 319
 320 def setup(app):
 321     table_file = dirname(__file__) + '/nics/overview_table.txt'
 322     generate_nic_overview_table(table_file)
 323
 324     if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
 325         print('Upgrade sphinx to version >= 1.3.1 for '
 326               'improved Figure/Table number handling.')
 327         # Add a role to handle :numref: references.
 328         app.add_role('numref', numref_role)
 329         # Process the numref references once the doctree has been created.
 330         app.connect('doctree-resolved', process_numref)