maintainers: update for ring library
[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 th, table#idx td {
318          text-align: center;
319       }
320       table#idx th {
321          font-size: 72%;
322          white-space: pre-wrap;
323          vertical-align: top;
324          padding: 0.5em 0;
325          min-width: 0.9em;
326          width: 2em;
327       }
328       table#idx col:first-child {
329          width: 0;
330       }
331       table#idx th:first-child {
332          vertical-align: bottom;
333       }
334       table#idx td {
335          font-size: 70%;
336          padding: 1px;
337       }
338       table#idx td:first-child {
339          padding-left: 1em;
340          text-align: left;
341       }
342       table#idx tr:nth-child(2n-1) td {
343          background-color: rgba(210, 210, 210, 0.2);
344       }
345       table#idx th:not(:first-child):hover,
346       table#idx td:not(:first-child):hover {
347          position: relative;
348       }
349       table#idx th:not(:first-child):hover::after,
350       table#idx td:not(:first-child):hover::after {
351          content: '';
352          height: 6000px;
353          top: -3000px;
354          width: 100%;
355          left: 0;
356          position: absolute;
357          z-index: -1;
358          background-color: #ffb;
359       }
360       table#idx tr:hover td {
361          background-color: #ffb;
362       }
363    </style>
364 """
365     print(template.replace("idx", "id%d" % (table_id)), file=outfile)
366
367
368 def setup(app):
369     table_file = dirname(__file__) + '/nics/overview_table.txt'
370     generate_overview_table(table_file, 1,
371                             'Features',
372                             'Features availability in networking drivers',
373                             'Feature')
374     table_file = dirname(__file__) + '/cryptodevs/overview_feature_table.txt'
375     generate_overview_table(table_file, 1,
376                             'Features',
377                             'Features availability in crypto drivers',
378                             'Feature')
379     table_file = dirname(__file__) + '/cryptodevs/overview_cipher_table.txt'
380     generate_overview_table(table_file, 2,
381                             'Cipher',
382                             'Cipher algorithms in crypto drivers',
383                             'Cipher algorithm')
384     table_file = dirname(__file__) + '/cryptodevs/overview_auth_table.txt'
385     generate_overview_table(table_file, 3,
386                             'Auth',
387                             'Authentication algorithms in crypto drivers',
388                             'Authentication algorithm')
389     table_file = dirname(__file__) + '/cryptodevs/overview_aead_table.txt'
390     generate_overview_table(table_file, 4,
391                             'AEAD',
392                             'AEAD algorithms in crypto drivers',
393                             'AEAD algorithm')
394     table_file = dirname(__file__) + '/cryptodevs/overview_asym_table.txt'
395     generate_overview_table(table_file, 5,
396                             'Asymmetric',
397                             'Asymmetric algorithms in crypto drivers',
398                             'Asymmetric algorithm')
399     table_file = dirname(__file__) + '/compressdevs/overview_feature_table.txt'
400     generate_overview_table(table_file, 1,
401                             'Features',
402                             'Features availability in compression drivers',
403                             'Feature')
404     table_file = dirname(__file__) + '/vdpadevs/overview_feature_table.txt'
405     generate_overview_table(table_file, 1,
406                             'Features',
407                             'Features availability in vDPA drivers',
408                             'Feature')
409
410     if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
411         print('Upgrade sphinx to version >= 1.3.1 for '
412               'improved Figure/Table number handling.')
413         # Add a role to handle :numref: references.
414         app.add_role('numref', numref_role)
415         # Process the numref references once the doctree has been created.
416         app.connect('doctree-resolved', process_numref)
417
418     app.add_stylesheet('css/custom.css')