ring: check flag settings for future proofing
[dpdk.git] / doc / guides / conf.py
1 # SPDX-License-Identifier: BSD-3-Clause
2 # Copyright(c) 2010-2015 Intel Corporation
3
4 from __future__ import print_function
5 import subprocess
6 from docutils import nodes
7 from distutils.version import LooseVersion
8 from sphinx import __version__ as sphinx_version
9 from sphinx.highlighting import PygmentsBridge
10 from pygments.formatters.latex import LatexFormatter
11 from os import listdir
12 from os import environ
13 from os.path import basename
14 from os.path import dirname
15 from os.path import join as path_join
16
17 try:
18     # Python 2.
19     import ConfigParser as configparser
20 except:
21     # Python 3.
22     import configparser
23
24 try:
25     import sphinx_rtd_theme
26
27     html_theme = "sphinx_rtd_theme"
28     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
29 except:
30     print('Install the sphinx ReadTheDocs theme for improved html documentation '
31           'layout: pip install sphinx_rtd_theme')
32     pass
33
34 project = 'Data Plane Development Kit'
35 html_logo = '../logo/DPDK_logo_vertical_rev_small.png'
36 latex_logo = '../logo/DPDK_logo_horizontal_tag.png'
37 html_add_permalinks = ""
38 html_show_copyright = False
39 highlight_language = 'none'
40
41 # If MAKEFLAGS is exported by the user, garbage text might end up in version
42 version = subprocess.check_output(['make', '-sRrC', '../../', 'showversion'],
43                                   env=dict(environ, MAKEFLAGS=""))
44 version = version.decode('utf-8').rstrip()
45 release = version
46
47 master_doc = 'index'
48
49 # Maximum feature description string length
50 feature_str_len = 25
51
52 # Figures, tables and code-blocks automatically numbered if they have caption
53 numfig = True
54
55 latex_documents = [
56     ('index',
57      'doc.tex',
58      '',
59      '',
60      'manual')
61 ]
62
63 # Latex directives to be included directly in the latex/pdf docs.
64 custom_latex_preamble = r"""
65 \usepackage{textalpha}
66 \RecustomVerbatimEnvironment{Verbatim}{Verbatim}{xleftmargin=5mm}
67 \usepackage{etoolbox}
68 \robustify\(
69 \robustify\)
70 """
71
72 # Configuration for the latex/pdf docs.
73 latex_elements = {
74     'papersize': 'a4paper',
75     'pointsize': '11pt',
76     # remove blank pages
77     'classoptions': ',openany,oneside',
78     'babel': '\\usepackage[english]{babel}',
79     # customize Latex formatting
80     'preamble': custom_latex_preamble
81 }
82
83
84 # Override the default Latex formatter in order to modify the
85 # code/verbatim blocks.
86 class CustomLatexFormatter(LatexFormatter):
87     def __init__(self, **options):
88         super(CustomLatexFormatter, self).__init__(**options)
89         # Use the second smallest font size for code/verbatim blocks.
90         self.verboptions = r'formatcom=\footnotesize'
91
92 # Replace the default latex formatter.
93 PygmentsBridge.latex_formatter = CustomLatexFormatter
94
95 # Configuration for man pages
96 man_pages = [("testpmd_app_ug/run_app", "testpmd",
97               "tests for dpdk pmds", "", 1),
98              ("tools/pdump", "dpdk-pdump",
99               "enable packet capture on dpdk ports", "", 1),
100              ("tools/proc_info", "dpdk-procinfo",
101               "access dpdk port stats and memory info", "", 1),
102              ("tools/pmdinfo", "dpdk-pmdinfo",
103               "dump a PMDs hardware support info", "", 1),
104              ("tools/devbind", "dpdk-devbind",
105               "check device status and bind/unbind them from drivers", "", 8)]
106
107
108 # ####### :numref: fallback ########
109 # The following hook functions add some simple handling for the :numref:
110 # directive for Sphinx versions prior to 1.3.1. The functions replace the
111 # :numref: reference with a link to the target (for all Sphinx doc types).
112 # It doesn't try to label figures/tables.
113 def numref_role(reftype, rawtext, text, lineno, inliner):
114     """
115     Add a Sphinx role to handle numref references. Note, we can't convert
116     the link here because the doctree isn't build and the target information
117     isn't available.
118     """
119     # Add an identifier to distinguish numref from other references.
120     newnode = nodes.reference('',
121                               '',
122                               refuri='_local_numref_#%s' % text,
123                               internal=True)
124     return [newnode], []
125
126
127 def process_numref(app, doctree, from_docname):
128     """
129     Process the numref nodes once the doctree has been built and prior to
130     writing the files. The processing involves replacing the numref with a
131     link plus text to indicate if it is a Figure or Table link.
132     """
133
134     # Iterate over the reference nodes in the doctree.
135     for node in doctree.traverse(nodes.reference):
136         target = node.get('refuri', '')
137
138         # Look for numref nodes.
139         if target.startswith('_local_numref_#'):
140             target = target.replace('_local_numref_#', '')
141
142             # Get the target label and link information from the Sphinx env.
143             data = app.builder.env.domains['std'].data
144             docname, label, _ = data['labels'].get(target, ('', '', ''))
145             relative_url = app.builder.get_relative_uri(from_docname, docname)
146
147             # Add a text label to the link.
148             if target.startswith('figure'):
149                 caption = 'Figure'
150             elif target.startswith('table'):
151                 caption = 'Table'
152             else:
153                 caption = 'Link'
154
155             # New reference node with the updated link information.
156             newnode = nodes.reference('',
157                                       caption,
158                                       refuri='%s#%s' % (relative_url, label),
159                                       internal=True)
160             node.replace_self(newnode)
161
162
163 def generate_overview_table(output_filename, table_id, section, table_name, title):
164     """
165     Function to generate the Overview Table from the ini files that define
166     the features for each driver.
167
168     The default features for the table and their order is defined by the
169     'default.ini' file.
170
171     """
172     # Default warning string.
173     warning = 'Warning generate_overview_table()'
174
175     # Get the default features and order from the 'default.ini' file.
176     ini_path = path_join(dirname(output_filename), 'features')
177     config = configparser.ConfigParser()
178     config.optionxform = str
179     config.read(path_join(ini_path, 'default.ini'))
180     default_features = config.items(section)
181
182     # Create a dict of the valid features to validate the other ini files.
183     valid_features = {}
184     max_feature_length = 0
185     for feature in default_features:
186         key = feature[0]
187         valid_features[key] = ' '
188         max_feature_length = max(max_feature_length, len(key))
189
190     # Get a list of driver ini files, excluding 'default.ini'.
191     ini_files = [basename(file) for file in listdir(ini_path)
192                  if file.endswith('.ini') and file != 'default.ini']
193     ini_files.sort()
194
195     # Build up a list of the table header names from the ini filenames.
196     pmd_names = []
197     for ini_filename in ini_files:
198         name = ini_filename[:-4]
199         name = name.replace('_vf', 'vf')
200         pmd_names.append(name)
201
202     # Pad the table header names.
203     max_header_len = len(max(pmd_names, key=len))
204     header_names = []
205     for name in pmd_names:
206         if '_vec' in name:
207             pmd, vec = name.split('_')
208             name = '{0:{fill}{align}{width}}vec'.format(pmd,
209                     fill='.', align='<', width=max_header_len-3)
210         else:
211             name = '{0:{fill}{align}{width}}'.format(name,
212                     fill=' ', align='<', width=max_header_len)
213         header_names.append(name)
214
215     # Create a dict of the defined features for each driver from the ini files.
216     ini_data = {}
217     for ini_filename in ini_files:
218         config = configparser.ConfigParser()
219         config.optionxform = str
220         config.read(path_join(ini_path, ini_filename))
221
222         # Initialize the dict with the default.ini value.
223         ini_data[ini_filename] = valid_features.copy()
224
225         # Check for a valid ini section.
226         if not config.has_section(section):
227             print("{}: File '{}' has no [{}] secton".format(warning,
228                                                             ini_filename,
229                                                             section))
230             continue
231
232         # Check for valid features names.
233         for name, value in config.items(section):
234             if name not in valid_features:
235                 print("{}: Unknown feature '{}' in '{}'".format(warning,
236                                                                 name,
237                                                                 ini_filename))
238                 continue
239
240             if value:
241                 # Get the first letter only.
242                 ini_data[ini_filename][name] = value[0]
243
244     # Print out the RST Driver Overview table from the ini file data.
245     outfile = open(output_filename, 'w')
246     num_cols = len(header_names)
247
248     print_table_css(outfile, table_id)
249     print('.. table:: ' + table_name + '\n', file=outfile)
250     print_table_header(outfile, num_cols, header_names, title)
251     print_table_body(outfile, num_cols, ini_files, ini_data, default_features)
252
253
254 def print_table_header(outfile, num_cols, header_names, title):
255     """ Print the RST table header. The header names are vertical. """
256     print_table_divider(outfile, num_cols)
257
258     line = ''
259     for name in header_names:
260         line += ' ' + name[0]
261
262     print_table_row(outfile, title, line)
263
264     for i in range(1, len(header_names[0])):
265         line = ''
266         for name in header_names:
267             line += ' ' + name[i]
268
269         print_table_row(outfile, '', line)
270
271     print_table_divider(outfile, num_cols)
272
273
274 def print_table_body(outfile, num_cols, ini_files, ini_data, default_features):
275     """ Print out the body of the table. Each row is a NIC feature. """
276
277     for feature, _ in default_features:
278         line = ''
279
280         for ini_filename in ini_files:
281             line += ' ' + ini_data[ini_filename][feature]
282
283         print_table_row(outfile, feature, line)
284
285     print_table_divider(outfile, num_cols)
286
287
288 def print_table_row(outfile, feature, line):
289     """ Print a single row of the table with fixed formatting. """
290     line = line.rstrip()
291     print('   {:<{}}{}'.format(feature, feature_str_len, line), file=outfile)
292
293
294 def print_table_divider(outfile, num_cols):
295     """ Print the table divider line. """
296     line = ' '
297     column_dividers = ['='] * num_cols
298     line += ' '.join(column_dividers)
299
300     feature = '=' * feature_str_len
301
302     print_table_row(outfile, feature, line)
303
304
305 def print_table_css(outfile, table_id):
306     template = """
307 .. raw:: html
308
309    <style>
310       .wy-nav-content {
311          opacity: .99;
312       }
313       table#idx {
314          cursor: default;
315          overflow: hidden;
316       }
317       table#idx p {
318          margin: 0;
319          line-height: inherit;
320       }
321       table#idx th, table#idx td {
322          text-align: center;
323          border: solid 1px #ddd;
324       }
325       table#idx th {
326          padding: 0.5em 0;
327       }
328       table#idx th, table#idx th p {
329          font-size: 11px;
330          white-space: pre-wrap;
331          vertical-align: top;
332          min-width: 0.9em;
333       }
334       table#idx col:first-child {
335          width: 0;
336       }
337       table#idx th:first-child {
338          vertical-align: bottom;
339       }
340       table#idx td {
341          padding: 1px;
342       }
343       table#idx td, table#idx td p {
344          font-size: 11px;
345       }
346       table#idx td:first-child {
347          padding-left: 1em;
348          text-align: left;
349       }
350       table#idx tr:nth-child(2n-1) td {
351          background-color: rgba(210, 210, 210, 0.2);
352       }
353       table#idx th:not(:first-child):hover,
354       table#idx td:not(:first-child):hover {
355          position: relative;
356       }
357       table#idx th:not(:first-child):hover::after,
358       table#idx td:not(:first-child):hover::after {
359          content: '';
360          height: 6000px;
361          top: -3000px;
362          width: 100%;
363          left: 0;
364          position: absolute;
365          z-index: -1;
366          background-color: #ffb;
367       }
368       table#idx tr:hover td {
369          background-color: #ffb;
370       }
371    </style>
372 """
373     print(template.replace("idx", "id%d" % (table_id)), file=outfile)
374
375
376 def setup(app):
377     table_file = dirname(__file__) + '/nics/overview_table.txt'
378     generate_overview_table(table_file, 1,
379                             'Features',
380                             'Features availability in networking drivers',
381                             'Feature')
382     table_file = dirname(__file__) + '/cryptodevs/overview_feature_table.txt'
383     generate_overview_table(table_file, 1,
384                             'Features',
385                             'Features availability in crypto drivers',
386                             'Feature')
387     table_file = dirname(__file__) + '/cryptodevs/overview_cipher_table.txt'
388     generate_overview_table(table_file, 2,
389                             'Cipher',
390                             'Cipher algorithms in crypto drivers',
391                             'Cipher algorithm')
392     table_file = dirname(__file__) + '/cryptodevs/overview_auth_table.txt'
393     generate_overview_table(table_file, 3,
394                             'Auth',
395                             'Authentication algorithms in crypto drivers',
396                             'Authentication algorithm')
397     table_file = dirname(__file__) + '/cryptodevs/overview_aead_table.txt'
398     generate_overview_table(table_file, 4,
399                             'AEAD',
400                             'AEAD algorithms in crypto drivers',
401                             'AEAD algorithm')
402     table_file = dirname(__file__) + '/cryptodevs/overview_asym_table.txt'
403     generate_overview_table(table_file, 5,
404                             'Asymmetric',
405                             'Asymmetric algorithms in crypto drivers',
406                             'Asymmetric algorithm')
407     table_file = dirname(__file__) + '/compressdevs/overview_feature_table.txt'
408     generate_overview_table(table_file, 1,
409                             'Features',
410                             'Features availability in compression drivers',
411                             'Feature')
412     table_file = dirname(__file__) + '/vdpadevs/overview_feature_table.txt'
413     generate_overview_table(table_file, 1,
414                             'Features',
415                             'Features availability in vDPA drivers',
416                             'Feature')
417     table_file = dirname(__file__) + '/bbdevs/overview_feature_table.txt'
418     generate_overview_table(table_file, 1,
419                             'Features',
420                             'Features availability in bbdev drivers',
421                             'Feature')
422
423     if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
424         print('Upgrade sphinx to version >= 1.3.1 for '
425               'improved Figure/Table number handling.')
426         # Add a role to handle :numref: references.
427         app.add_role('numref', numref_role)
428         # Process the numref references once the doctree has been created.
429         app.connect('doctree-resolved', process_numref)
430
431     try:
432         # New function in sphinx 1.8
433         app.add_css_file('css/custom.css')
434     except:
435         app.add_stylesheet('css/custom.css')