When using Python 3.10, this warning appears:
DeprecationWarning: The distutils package is deprecated
and slated for removal in Python 3.12.
Use setuptools or check PEP 632 for potential alternatives
The PEP 632 recommends replacing "distutils.version" with "packaging".
Bugzilla ID: 914
Cc: stable@dpdk.org
Reported-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Tested-by: Jerin Jacob <jerinj@marvell.com>
Patch adds feature matrices for event dev, Rx/Tx, Crypto
and Timer adapters.
Along with, .ini files are added for all supported PMDs.
Signed-off-by: Sunil Kumar Kori <skori@marvell.com>
In heterogeneous computing system, processing is not only in the CPU.
Some tasks can be delegated to devices working in parallel.
The new library gpudev is for dealing with GPGPU computing devices
from a DPDK application running on the CPU.
The infrastructure is prepared to welcome drivers in drivers/gpu/.
Signed-off-by: Elena Agostini <eagostini@nvidia.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Added table to the crypto device drivers documentation
stating the support of each PMD on Linux, FreeBSD and Windows.
Signed-off-by: Tal Shnaiderman <talshn@nvidia.com>
Acked-by: Akhil Goyal <gakhil@marvell.com>
The NICs overview table lists all supported features per driver.
There was a single row for "Flow API",
although rte_flow is composed of many items and actions.
The row "Flow API" is replaced with two new tables for items and actions.
Also, since rte_flow is not implemented in all drivers,
it would be ugly to add empty sections in some files.
That's why the error message for missing INI section is removed.
The lists are sorted alphabetically.
The extra files for some VF and vectorized data paths are not filled.
Signed-off-by: Asaf Penso <asafp@nvidia.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Kiran Kumar K <kirankumark@marvell.com>
---
v6 changes:
- rebase/update
- remove deprecated shared action
The documentation is generated in HTML only.
The PDF format is abandoned since DPDK 20.11
while dropping support of the make-based build.
This decision has been mentioned by the Technical Board:
https://mails.dpdk.org/archives/dev/2021-January/195549.html
Fixes: 3cc6ecfdfe ("build: remove makefiles")
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
Sphinx 4.0 became stricter with permalink configuration:
"
html_add_permalinks has been deprecated since v3.5.0.
Please use html_permalinks and html_permalinks_icon instead.
"
The new variable is used while keeping compatibility
with older Sphinx versions.
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
If the rtd theme is available, passing it by name is enough to select
it. Sphinx itself recognises the "sphinx_rtd_theme" name as a special
case and tries to find its path automatically.
On the other hand, passing a html_theme_path makes sphinx parse all
themes availables in this path, which in some environment (like GHA) is
/usr/share and makes sphinx error on the first zipfile it finds (in GHA,
some Azure CLI thingy) that has no sphinx theme in it.
Fixes: 46562be650 ("doc: import sphinx rtd theme when available")
Cc: stable@dpdk.org
Signed-off-by: David Marchand <david.marchand@redhat.com>
Acked-by: Aaron Conole <aconole@redhat.com>
Currently, when building sphinx documentation, the build will only
succeed if being run from the build system, because the conf.py script
expects DPDK_VERSION environment variable to be set, and crashes if it
is not.
However, there are certain external tools (such as sphinx documentation
preview extensions for certain IDE's) that use live preview and thus
rely on running their own sphinx commands. In these cases, it is useful
to permit building sphinx documentation without specifying the
DPDK_VERSION environment variable. The version string is the only thing
preventing manual sphinx build commands from working.
Fix the conf.py to use "None" as a version string in cases when
DPDK_VERSION environment variable is not set.
Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
When running Sphinx through ninja, the wrapper configured in meson
redirects stdout to a log file.
It makes more important to print issues on stderr.
Some warnings generated by the conf.py were hidden because
printed on stdout. The first improvement is to print them on stderr.
The second measure is to stop processing if meson was configured
with --werror.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
The DPDK version should appear in the top left corner of the HTML guides.
When dropping make, the variable version has been removed,
so Sphinx stopped integrating the version number.
Fixes: a4362f1502 ("doc: build without using make")
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Python 2 support has now been dropped. Remove references to it in the
documentation.
Since all python scripts now have a proper shebang that calls python3,
execute the scripts directly without specifying the interpreter.
Sphinx version from most Linux distros is OK in 2020, do not encourage
people to break their system by installing with pip. Use the distros
official packages.
Signed-off-by: Robin Jarry <robin.jarry@6wind.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Kevin Laatz <kevin.laatz@intel.com>
Changed scripts to explicitly use Python 3 only, to avoid
maintaining Python 2.
Removed deprecation notices.
Signed-off-by: Louise Kilheeney <louise.kilheeney@intel.com>
Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Robin Jarry <robin.jarry@6wind.com>
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Ray Kinsella <mdr@ashroe.eu>
When building the DPDK guide documents, the DPDK version information was
pulled using "make showversion", which meant there was a dependency on
the DPDK make-based build system. Change this to have the version info
passed in from meson itself.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
This commit introduce the RegEx poll mode drivers class, and
adds Mellanox RegEx PMD.
Signed-off-by: Yuval Avnery <yuvalav@mellanox.com>
Signed-off-by: Ori Kam <orika@mellanox.com>
Adding missing overview page in documentation with
comparison of feature set by each available PMD implementation.
Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
Acked-by: Dave Burley <dave.burley@accelercomm.com>
Acked-by: Niall Power <niall.power@intel.com>
Acked-by: Akhil Goyal <akhil.goyal@nxp.com>
It seems sphinx >= 2.0 is inserting a <p> tag in each table cell.
The feature table (matrix) style needs to be updated to avoid
cells being too big.
The margin, padding and line height are overridden.
The font size in percentage is replaced with an equivalent pixel size.
The border is explicit because it disappeared for th.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
The function add_stylesheet() is deprecated since sphinx 1.8.
It will be removed in sphinx 4.0.
It is replaced by add_css_file().
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Add vDPA devices features table and explanation.
Any vDPA driver can add its own supported features by ading a new ini
file to the features directory in doc/guides/vdpadevs/features.
Signed-off-by: Matan Azrad <matan@mellanox.com>
After upgrading to python-3.8.0, a syntax mismatch is revealed:
doc/guides/conf.py:240: SyntaxWarning: "is not" with a literal.
Did you mean "!="?
if value is not '':
Removing "is not ''" seems the right thing to do.
A patch may also be needed in the RTD theme package:
https://github.com/readthedocs/sphinx_rtd_theme/commit/a49a812c.diff
(not included in release 0.4.3)
Fixes: 9db3f52126 ("doc: generate NIC overview table from ini files")
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
For an unknown reason, the sign "μ" is not accepted by some environments,
probably due to the version of some Latex packages or dependencies.
! Package inputenc Error: Unicode character μ (U+03BC)
(inputenc) not set up for use with LaTeX.
It is fixed by installing texlive-langgreek.
Fixes: d0dff9ba44 ("doc: sample application user guide")
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
In some environment like the current dpdk.org server,
there can be some errors due to symbols in titles,
as it was the case before this commit in DPDK 18.05:
commit 551d148944 ("doc: remove flow API migration section")
! LaTeX Error: Bad math environment delimiter.
It can be avoided thanks to the Latex command \robustify.
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
If the user has MAKEFLAGS set in the environment when building the
documentation, the doc/guides/conf.py script which calls "make"
exclusively to get the project version might pick up garbage from
stdout, like:
<title>FAQ — Data Plane Development Kit make[2]:
Entering directory '/build/1st/dpdk-18.11/doc/guides'
18.11.0
make[2]: Leaving directory '/build/1st/dpdk-18.11'
documentation</title>
Override MAKEFLAGS in the Python subprocess call to avoid this issue.
Fixes: f7aaae2fe6 ("doc: add copyright and version")
Cc: stable@dpdk.org
Signed-off-by: Luca Boccassi <bluca@debian.org>
This adds general compression drivers feature guide
as well as the ISA-L PMD documentation and guide.
Signed-off-by: Lee Daly <lee.daly@intel.com>
Reviewed-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
The length of the longest header name is used to adjust the padding
of the header row automatically, instead of fixed length.
The previous length (10) was too short for vdev_netvsc.
Fixes: 6086ab3bb3 ("net/vdev_netvsc: introduce Hyper-V platform driver")
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
The font size of the header row is reduced in order to shrink
the column size of the tables.
It is required for the NICs features table which is too large to fit
in the page width.
Cc: stable@dpdk.org
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Vertical spacing is lower before an item title than after.
So the items with paragraphs are not well separated.
A custom CSS is added to override the rtd theme.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
The net PMD overview table is big and required to be shrunk.
The crypto PMD tables had variable column sizes: the latest
columns were smaller.
The minimum width is set to 0.9em without any forced padding.
The maximum width is set to 2em.
The width of the first column set by sphinx is overridden to 0
for full elasticity.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
The ReadTheDocs theme is no longer available by default in
Sphinx versions >= 1.3.1 and if it isn't available then an
exception is raised. This patch imports the ReadTheDocs
theme when it is available and warns but proceeds when it
isn't.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
There were several tables in NIC and crypto guides with the same
copy-pasted CSS addition.
It is moved into one unique place: conf.py.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
Seen with recent version of sphinx:
WARNING: latex_preamble conflicts with latex_elements['preamble'], ignored.
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Tested-by: Ferruh Yigit <ferruh.yigit@intel.com>
Follow the approach in the network devices overview,
for the feature matrix, so it improves readibility
and maintainability.
Signed-off-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Add a new API to force free consumed buffers on Tx ring. API will return
the number of packets freed (0-n) or error code if feature not supported
(-ENOTSUP) or input invalid (-ENODEV).
Signed-off-by: Billy McFall <bmcfall@redhat.com>
Acked-by: Keith Wiles <keith.wiles@intel.com>
Make all DPDK python application compliant with the PEP8 standard
to allow for consistency checking of patches and to allow further
refactoring.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Fix relative path between sphinx conf.py file and Nic table file
to allow automatic build on ReadTheDocs.
Fixes: 9db3f52126 ("doc: generate NIC overview table from ini files")
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Tested-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
This summarizes the "how to call dpdk-devbind" in one place to be
picked up by html/pdf/man-page docs.
That knowledge was available before but spread in various docs along
examples (which are great and have to be kept) as well as in the
--usage/--help option of the tool itself.
As a root only program in sbin it should belong to section 8
"8 System administration commands (usually only for root)"
Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Acked-by: Luca Boccassi <lboccass@brocade.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
This summarizes the "how to call dpdk-pmdinfo" in one place to be picked
up by html/pdf/man-page docs.
Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Acked-by: Luca Boccassi <lboccass@brocade.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
This enables the rendering of rst into man pages as well as installing
them (if built) along the binaries. To do so there is a new make target
"doc-guides-man" which will render the rst files into man format.
Currently these three tools had docs that were compatible "enough" to
make up for a reasonable manpage.
- testpmd
- dpdk-pdump
- dpdk-procinfo
Since a man page should be installed along the binary they are not
installed in install-doc but install-runtime insteade. If not explicitly
built by the "doc-guides-man" target before calling install-runtime
there is no change to the old behaviour.
Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
Acked-by: Luca Boccassi <lboccass@brocade.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Convert the NIC feature table in the overview doc into a set of ini
files and add functions into the Sphinx conf.py file to auto-generate
them back into an RST table.
The reason for doing this is to make it easier for PMD maintainers to
update the feature matrix that makes up the table and to avoid
frequent and hard to resolve conflicts in doc/guides/nics/overview.rst.
A NIC/PMD feature matrix is now an ini file like the following:
$ head doc/guides/nics/nic_features/i40e.ini
;
; Features of the i40e network driver.
;
[Features]
Link status = Y
Link status event = Y
Rx interrupt = Y
Queue start/stop = Y
...
The output RST table matches the existing table with the column
headers sorted.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Tested-by: Ferruh Yigit <ferruh.yigit@intel.com>
Fix issue where the navigation levels weren't displayed in the
html sidebar with the new read_the_docs theme.
This was due to the :titlesonly: directive in the high level
index.rst and also due to a stray newline in the parsed version
number.
Reported-by: Matthew Hall <mhall@mhcomputing.net>
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Change the Sphinx default theme from "alabaster" to the ReadTheDocs
theme. See for example:
http://dpdk.readthedocs.org/en/latest/
This looks better for technical documentation and in particular
it has a 80 char wide verbatim block rendering.
Also add logos for the html and latex docs.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Harry van Haaren <harry.van.haaren@intel.com>
Remove requirement for occasionally hard to find/install
DejaVuSansMono font. It isn't gnerally required anyway.
The default mono font is sufficient.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Harry van Haaren <harry.van.haaren@intel.com>
Turn off the permalink symbol in the Sphinx generated html docs.
This is a distracting mouseover when reading the docs and links
to sections can still be obtained from the doc index.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Set the default literal block format for Sphinx docs
to 'none' instead of the implicit default of 'python'.
This means that default :: blocks won't have any
highlighting applied. Explicit highlighting via
the code-block:: directive is already available and
in use in the docs.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
This change adds automatic figure references to the docs. The
figure numbers in the generated Html and PDF docs are now
automatically numbered based on section.
Requires Sphinx >= 1.3.1.
The patch makes the following changes.
* Changes image:: tag to figure:: and moves image caption
to the figure.
* Adds captions to figures that didn't previously have any.
* Un-templates the |image-name| substitution definitions
into explicit figure:: tags. They weren't used more
than once anyway and Sphinx doesn't support them
for figure.
* Adds a target to each image that didn't previously
have one so that they can be cross-referenced.
* Renamed existing image target to match the image
name for consistency.
* Replaces the Figures lists with automatic :numref:
:ref: entries to generate automatic numbering
and captions.
* Replaces "Figure" references with automatic :numref:
references.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
This change adds some simple handling for the :numref: directive
for Sphinx versions prior to 1.3.1. This allows the Guides
documentation to be built with older versions of Sphinx and still
produce reasonable results.
The patch replaces the :numref: reference with a link to the
target (for all Sphinx doc types). It doesn't try to label
figures/tables.
Full numref support with automatic figure/table numbering and
links can be obtained by upgrading to Sphinx 1.3.1 or later.
Signed-off-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Thomas Monjalon <thomas.monjalon@6wind.com>
The "manual" Latex template provided by Sphinx introduce a lot
of useless and confusing blank pages.
Let's remove them.
Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
