Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/133924/?format=api
{ "id": 133924, "url": "http://patches.dpdk.org/api/patches/133924/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-24-juraj.linkes@pantheon.tech/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20231106171601.160749-24-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231106171601.160749-24-juraj.linkes@pantheon.tech", "date": "2023-11-06T17:16:01", "name": "[v5,23/23] dts: add doc generation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "07ec25863b22a722b63eff4927c3ae3e9de590fb", "submitter": { "id": 1626, "url": "http://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 2642, "url": "http://patches.dpdk.org/api/users/2642/?format=api", "username": "mcoquelin", "first_name": "Maxime", "last_name": "Coquelin", "email": "maxime.coquelin@redhat.com" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-24-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30173, "url": "http://patches.dpdk.org/api/series/30173/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30173", "date": "2023-11-06T17:15:38", "name": "dts: add dts api docs", "version": 5, "mbox": "http://patches.dpdk.org/series/30173/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/133924/comments/", "check": "fail", "checks": "http://patches.dpdk.org/api/patches/133924/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 62415432BB;\n\tMon, 6 Nov 2023 18:19:26 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id BAC3642DF8;\n\tMon, 6 Nov 2023 18:16:39 +0100 (CET)", "from mail-ed1-f43.google.com (mail-ed1-f43.google.com\n [209.85.208.43]) by mails.dpdk.org (Postfix) with ESMTP id 9290340633\n for <dev@dpdk.org>; Mon, 6 Nov 2023 18:16:36 +0100 (CET)", "by mail-ed1-f43.google.com with SMTP id\n 4fb4d7f45d1cf-5440f25dcc7so5880926a12.0\n for <dev@dpdk.org>; Mon, 06 Nov 2023 09:16:36 -0800 (PST)", "from jlinkes-PT-Latitude-5530.. (ip-46.34.243.197.o2inet.sk.\n [46.34.243.197]) by smtp.gmail.com with ESMTPSA id\n s10-20020a170906354a00b009b947aacb4bsm47016eja.191.2023.11.06.09.16.34\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Mon, 06 Nov 2023 09:16:35 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1699290996; x=1699895796; darn=dpdk.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=U2eOVOixY1+yF1+bz5Tb1SyLRJ/VENv/zSH/yt69Mcc=;\n b=RWrFG0uvXcKGPcDw9wev7eZfl1Nqfl7qTPI5WKNOA8nmuW52+7Srs22In7bvCQEt0w\n Gt857lN4wh+i/bWf85Xe2dL0g8FHTkSBEANFFg9ZX4M4IY8LrO9+oAbUfgmTDu5PIj+q\n eGfYU6UvJWJUqTtryMgFBupCdp+AaczIHmlTQfK0MkouI505LoIgr23PR5DI1lYZc14L\n Pff3nxoM9b/cjsZ204wKsvbPTYziW7Fey0xkOx8qMC95awEXgpXjNfSCLOLKymm01GZi\n 8bRA8CM5mfkzNDBvXtuwm7xkHb+fcYYj7i13sDt9Mi7VUfDOTTmhh7FcmNZPmBFbkCQN\n UHTw==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1699290996; x=1699895796;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n :subject:date:message-id:reply-to;\n bh=U2eOVOixY1+yF1+bz5Tb1SyLRJ/VENv/zSH/yt69Mcc=;\n b=UuJ7FxLpoV2JBFhJ60E60c1FggdImXEsNBCHYcMuKK/DY4ucVdD6YGSz8MLBy9qkm7\n EUYQUIMPG9rGNGyR6VJVLrCHDwog1k5bYQJYgiSD5E42LQ00ydL0k3d+pzGmiVkQ6ceu\n 4OgVxgeT4hw6BZ47OrX4Ecvc3Opcai5XEiEEt8ae8i8wjmcfli+6wHMnzteH3a37BtfA\n g7NHCacvQf1zC+FqdtGM7BMObzGRdZnuN50xyMKE9C5pn44WxeW84+rtqZOfUVwI0fw8\n EpJel0/5r99GwEV5O6vUjsm/lkKmtSQ05eJ4K30UmTXJWVliX4Ng+7IVyz/8TFfZXwmf\n 3Jsg==", "X-Gm-Message-State": "AOJu0YxwKm8ICzgZPSlMSZv5OYNI3fzt8DCrIH46hTZNP7OuyfhhuCP3\n sV6ZZGp2P5s9u/3LIEU09/53baIR1/QfjbHzmrOaFw==", "X-Google-Smtp-Source": "\n AGHT+IFwrtS56wkToihI9jivl4ASIRs2WE7PgE0H90Mn9zos1zH7tLjA5nUXvQ3B7jF6FQlwCTFZsg==", "X-Received": "by 2002:a17:907:608e:b0:9c7:5667:5648 with SMTP id\n ht14-20020a170907608e00b009c756675648mr15297570ejc.51.1699290996242;\n Mon, 06 Nov 2023 09:16:36 -0800 (PST)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com,\n bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu,\n paul.szczepanek@arm.com, yoan.picchi@foss.arm.com", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v5 23/23] dts: add doc generation", "Date": "Mon, 6 Nov 2023 18:16:01 +0100", "Message-Id": "<20231106171601.160749-24-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231106171601.160749-1-juraj.linkes@pantheon.tech>", "References": "<20230831100407.59865-1-juraj.linkes@pantheon.tech>\n <20231106171601.160749-1-juraj.linkes@pantheon.tech>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "The tool used to generate developer docs is Sphinx, which is already\nused in DPDK. The same configuration is used to preserve style, but it's\nbeen augmented with doc-generating configuration and a change to how the\nsidebar displays the content hierarchy.\n\nSphinx generates the documentation from Python docstrings. The docstring\nformat is the Google format [0] which requires the sphinx.ext.napoleon\nextension. The other extension, sphinx.ext.intersphinx, enables linking\nto object in external documentations, such as the Python documentation.\n\nThere are two requirements for building DTS docs:\n* The same Python version as DTS or higher, because Sphinx imports the\n code.\n* Also the same Python packages as DTS, for the same reason.\n\n[0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings\n\nSigned-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>\n---\n buildtools/call-sphinx-build.py | 29 ++++++++++++-------\n doc/api/meson.build | 1 +\n doc/guides/conf.py | 34 +++++++++++++++++++----\n doc/guides/meson.build | 1 +\n doc/guides/tools/dts.rst | 32 ++++++++++++++++++++-\n dts/doc/conf_yaml_schema.json | 1 +\n dts/doc/index.rst | 17 ++++++++++++\n dts/doc/meson.build | 49 +++++++++++++++++++++++++++++++++\n dts/meson.build | 16 +++++++++++\n meson.build | 1 +\n 10 files changed, 165 insertions(+), 16 deletions(-)\n create mode 120000 dts/doc/conf_yaml_schema.json\n create mode 100644 dts/doc/index.rst\n create mode 100644 dts/doc/meson.build\n create mode 100644 dts/meson.build", "diff": "diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py\nindex 39a60d09fa..c2f3acfb1d 100755\n--- a/buildtools/call-sphinx-build.py\n+++ b/buildtools/call-sphinx-build.py\n@@ -3,37 +3,46 @@\n # Copyright(c) 2019 Intel Corporation\n #\n \n+import argparse\n import sys\n import os\n from os.path import join\n from subprocess import run, PIPE, STDOUT\n from packaging.version import Version\n \n-# assign parameters to variables\n-(sphinx, version, src, dst, *extra_args) = sys.argv[1:]\n+parser = argparse.ArgumentParser()\n+parser.add_argument('sphinx')\n+parser.add_argument('version')\n+parser.add_argument('src')\n+parser.add_argument('dst')\n+parser.add_argument('--dts-root', default='.')\n+args, extra_args = parser.parse_known_args()\n \n # set the version in environment for sphinx to pick up\n-os.environ['DPDK_VERSION'] = version\n+os.environ['DPDK_VERSION'] = args.version\n+os.environ['DTS_ROOT'] = args.dts_root\n \n # for sphinx version >= 1.7 add parallelism using \"-j auto\"\n-ver = run([sphinx, '--version'], stdout=PIPE,\n+ver = run([args.sphinx, '--version'], stdout=PIPE,\n stderr=STDOUT).stdout.decode().split()[-1]\n-sphinx_cmd = [sphinx] + extra_args\n+sphinx_cmd = [args.sphinx] + extra_args\n if Version(ver) >= Version('1.7'):\n sphinx_cmd += ['-j', 'auto']\n \n # find all the files sphinx will process so we can write them as dependencies\n srcfiles = []\n-for root, dirs, files in os.walk(src):\n+for root, dirs, files in os.walk(args.src):\n srcfiles.extend([join(root, f) for f in files])\n \n # run sphinx, putting the html output in a \"html\" directory\n-with open(join(dst, 'sphinx_html.out'), 'w') as out:\n- process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],\n- stdout=out)\n+with open(join(args.dst, 'sphinx_html.out'), 'w') as out:\n+ process = run(\n+ sphinx_cmd + ['-b', 'html', args.src, join(args.dst, 'html')],\n+ stdout=out\n+ )\n \n # create a gcc format .d file giving all the dependencies of this doc build\n-with open(join(dst, '.html.d'), 'w') as d:\n+with open(join(args.dst, '.html.d'), 'w') as d:\n d.write('html: ' + ' '.join(srcfiles) + '\\n')\n \n sys.exit(process.returncode)\ndiff --git a/doc/api/meson.build b/doc/api/meson.build\nindex 5b50692df9..92fe10d9e7 100644\n--- a/doc/api/meson.build\n+++ b/doc/api/meson.build\n@@ -1,6 +1,7 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2018 Luca Boccassi <bluca@debian.org>\n \n+doc_api_build_dir = meson.current_build_dir()\n doxygen = find_program('doxygen', required: get_option('enable_docs'))\n \n if not doxygen.found()\ndiff --git a/doc/guides/conf.py b/doc/guides/conf.py\nindex 0f7ff5282d..169b1d24bc 100644\n--- a/doc/guides/conf.py\n+++ b/doc/guides/conf.py\n@@ -7,10 +7,9 @@\n from sphinx import __version__ as sphinx_version\n from os import listdir\n from os import environ\n-from os.path import basename\n-from os.path import dirname\n+from os.path import basename, dirname\n from os.path import join as path_join\n-from sys import argv, stderr\n+from sys import argv, stderr, path\n \n import configparser\n \n@@ -24,6 +23,31 @@\n file=stderr)\n pass\n \n+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.intersphinx']\n+\n+# Python docstring options\n+autodoc_default_options = {\n+ 'members': True,\n+ 'member-order': 'bysource',\n+ 'show-inheritance': True,\n+}\n+autodoc_class_signature = 'separated'\n+autodoc_typehints = 'both'\n+autodoc_typehints_format = 'short'\n+autodoc_typehints_description_target = 'documented'\n+napoleon_numpy_docstring = False\n+napoleon_attr_annotations = True\n+napoleon_preprocess_types = True\n+add_module_names = False\n+toc_object_entries = False\n+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}\n+\n+# Sidebar config\n+html_theme_options = {\n+ 'collapse_navigation': False,\n+ 'navigation_depth': -1,\n+}\n+\n stop_on_error = ('-W' in argv)\n \n project = 'Data Plane Development Kit'\n@@ -35,8 +59,8 @@\n html_show_copyright = False\n highlight_language = 'none'\n \n-release = environ.setdefault('DPDK_VERSION', \"None\")\n-version = release\n+path.append(environ.get('DTS_ROOT'))\n+version = environ.setdefault('DPDK_VERSION', \"None\")\n \n master_doc = 'index'\n \ndiff --git a/doc/guides/meson.build b/doc/guides/meson.build\nindex 51f81da2e3..8933d75f6b 100644\n--- a/doc/guides/meson.build\n+++ b/doc/guides/meson.build\n@@ -1,6 +1,7 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2018 Intel Corporation\n \n+doc_guides_source_dir = meson.current_source_dir()\n sphinx = find_program('sphinx-build', required: get_option('enable_docs'))\n \n if not sphinx.found()\ndiff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst\nindex b1e99107c3..2b96bb11f1 100644\n--- a/doc/guides/tools/dts.rst\n+++ b/doc/guides/tools/dts.rst\n@@ -283,7 +283,10 @@ When adding code to the DTS framework, pay attention to the rest of the code\n and try not to divert much from it. The :ref:`DTS developer tools <dts_dev_tools>` will issue\n warnings when some of the basics are not met.\n \n-The code must be properly documented with docstrings. The style must conform to\n+The API documentation, which is a helpful reference when developing, may be accessed\n+in the code directly or generated with the `API docs build steps <building_api_docs>`_.\n+\n+Speaking of which, the code must be properly documented with docstrings. The style must conform to\n the `Google style <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.\n See an example of the style\n `here <https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>`_.\n@@ -408,3 +411,30 @@ There are three tools used in DTS to help with code checking, style and formatti\n These three tools are all used in ``devtools/dts-check-format.sh``,\n the DTS code check and format script.\n Refer to the script for usage: ``devtools/dts-check-format.sh -h``.\n+\n+\n+.. _building_api_docs:\n+\n+Building DTS API docs\n+---------------------\n+\n+To build DTS API docs, install the dependencies with Poetry, then enter its shell:\n+\n+.. code-block:: console\n+\n+ poetry install --with docs\n+ poetry shell\n+\n+The documentation is built using the standard DPDK build system. After executing the meson command\n+and entering Poetry's shell, build the documentation with:\n+\n+.. code-block:: console\n+\n+ ninja -C build dts-doc\n+\n+The output is generated in ``build/doc/api/dts/html``.\n+\n+.. Note::\n+\n+ Make sure to fix any Sphinx warnings when adding or updating docstrings. Also make sure to run\n+ the ``devtools/dts-check-format.sh`` script and address any issues it finds.\ndiff --git a/dts/doc/conf_yaml_schema.json b/dts/doc/conf_yaml_schema.json\nnew file mode 120000\nindex 0000000000..d89eb81b72\n--- /dev/null\n+++ b/dts/doc/conf_yaml_schema.json\n@@ -0,0 +1 @@\n+../framework/config/conf_yaml_schema.json\n\\ No newline at end of file\ndiff --git a/dts/doc/index.rst b/dts/doc/index.rst\nnew file mode 100644\nindex 0000000000..f5dcd553f2\n--- /dev/null\n+++ b/dts/doc/index.rst\n@@ -0,0 +1,17 @@\n+.. DPDK Test Suite documentation.\n+\n+Welcome to DPDK Test Suite's documentation!\n+===========================================\n+\n+.. toctree::\n+ :titlesonly:\n+ :caption: Contents:\n+\n+ framework\n+\n+Indices and tables\n+==================\n+\n+* :ref:`genindex`\n+* :ref:`modindex`\n+* :ref:`search`\ndiff --git a/dts/doc/meson.build b/dts/doc/meson.build\nnew file mode 100644\nindex 0000000000..d2e8c19789\n--- /dev/null\n+++ b/dts/doc/meson.build\n@@ -0,0 +1,49 @@\n+# SPDX-License-Identifier: BSD-3-Clause\n+# Copyright(c) 2023 PANTHEON.tech s.r.o.\n+\n+sphinx = find_program('sphinx-build')\n+sphinx_apidoc = find_program('sphinx-apidoc')\n+\n+if not sphinx.found() or not sphinx_apidoc.found()\n+ subdir_done()\n+endif\n+\n+dts_api_framework_dir = join_paths(dts_dir, 'framework')\n+dts_api_build_dir = join_paths(doc_api_build_dir, 'dts')\n+dts_api_src = custom_target('dts_api_src',\n+ output: 'modules.rst',\n+ command: ['SPHINX_APIDOC_OPTIONS=members,show-inheritance',\n+ sphinx_apidoc, '--append-syspath', '--force',\n+ '--module-first', '--separate', '-V', meson.project_version(),\n+ '--output-dir', dts_api_build_dir, '--no-toc', '--implicit-namespaces',\n+ dts_api_framework_dir],\n+ build_by_default: false)\n+doc_targets += dts_api_src\n+doc_target_names += 'DTS_API_sphinx_sources'\n+\n+cp = find_program('cp')\n+cp_index = custom_target('cp_index',\n+ input: ['index.rst', 'conf_yaml_schema.json'],\n+ output: 'index.rst',\n+ depends: dts_api_src,\n+ command: [cp, '--dereference', '@INPUT@', dts_api_build_dir],\n+ build_by_default: false)\n+doc_targets += cp_index\n+doc_target_names += 'DTS_API_sphinx_index'\n+\n+extra_sphinx_args = ['-E', '-c', doc_guides_source_dir, '--dts-root', dts_dir]\n+if get_option('werror')\n+ extra_sphinx_args += '-W'\n+endif\n+\n+htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')\n+dts_api_html = custom_target('dts_api_html',\n+ output: 'html',\n+ depends: cp_index,\n+ command: [sphinx_wrapper, sphinx, meson.project_version(),\n+ dts_api_build_dir, dts_api_build_dir, extra_sphinx_args],\n+ build_by_default: false,\n+ install: false,\n+ install_dir: htmldir)\n+doc_targets += dts_api_html\n+doc_target_names += 'DTS_API_HTML'\ndiff --git a/dts/meson.build b/dts/meson.build\nnew file mode 100644\nindex 0000000000..e8ce0f06ac\n--- /dev/null\n+++ b/dts/meson.build\n@@ -0,0 +1,16 @@\n+# SPDX-License-Identifier: BSD-3-Clause\n+# Copyright(c) 2023 PANTHEON.tech s.r.o.\n+\n+doc_targets = []\n+doc_target_names = []\n+dts_dir = meson.current_source_dir()\n+\n+subdir('doc')\n+\n+if doc_targets.length() == 0\n+ message = 'No docs targets found'\n+else\n+ message = 'Built docs:'\n+endif\n+run_target('dts-doc', command: [echo, message, doc_target_names],\n+ depends: doc_targets)\ndiff --git a/meson.build b/meson.build\nindex 2e6e546d20..c391bf8c71 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -87,6 +87,7 @@ subdir('app')\n \n # build docs\n subdir('doc')\n+subdir('dts')\n \n # build any examples explicitly requested - useful for developers - and\n # install any example code into the appropriate install path\n", "prefixes": [ "v5", "23/23" ] }