Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/126821/?format=api
{ "id": 126821, "url": "http://patches.dpdk.org/api/patches/126821/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20230511091408.236638-4-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": "<20230511091408.236638-4-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20230511091408.236638-4-juraj.linkes@pantheon.tech", "date": "2023-05-11T09:14:07", "name": "[RFC,v3,3/4] dts: add doc generation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "4c2921be37ed421e9e9552b2851ea9f54fe6ef68", "submitter": { "id": 1626, "url": "http://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20230511091408.236638-4-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 27977, "url": "http://patches.dpdk.org/api/series/27977/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=27977", "date": "2023-05-11T09:14:04", "name": "dts: add dts api docs", "version": 3, "mbox": "http://patches.dpdk.org/series/27977/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/126821/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/126821/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 B10F442A1B;\n\tThu, 11 May 2023 11:14:37 +0200 (CEST)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 5A87742DCC;\n\tThu, 11 May 2023 11:14:20 +0200 (CEST)", "from mail-ej1-f54.google.com (mail-ej1-f54.google.com\n [209.85.218.54]) by mails.dpdk.org (Postfix) with ESMTP id F1A2142D9B\n for <dev@dpdk.org>; Thu, 11 May 2023 11:14:16 +0200 (CEST)", "by mail-ej1-f54.google.com with SMTP id\n a640c23a62f3a-969f90d71d4so489108066b.3\n for <dev@dpdk.org>; Thu, 11 May 2023 02:14:16 -0700 (PDT)", "from localhost.localdomain (ip-46.34.233.151.o2inet.sk.\n [46.34.233.151]) by smtp.gmail.com with ESMTPSA id\n qa8-20020a170907868800b0096a2eaa508asm1710090ejc.168.2023.05.11.02.14.15\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Thu, 11 May 2023 02:14:16 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683796456;\n x=1686388456;\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=xajTdXEpezjJKaQbfSvApGR4iTAOWKtfCvREQginYZg=;\n b=cBpEwAZzyqnUWnTJeDWIFNuMM5GU6oHmmPaHDXT2bahIJEfRS/2pCQUrSJMxh4UTIl\n 4mdLre5bPwPaj2QXGyIqj8VlwpcGDGQLJr8MDL/VI8VwaIliok3zMpIPJl00vPQxBjh2\n T9EwxdgzYvMyG6MnG4CLwCIO63/6U2C2QPV+YHLK4RDYGC1CG5S7UaR4mQdf19zh7zhJ\n dyktvS6yfCth9983+GGZftgp3lZx2q+xnpMwiKgRYufWTtxp2KIy0ES6tnkvklUZmbXk\n f0J5YmVJzUxPDRzAVfDx5ciQOeEG3z/uPkedWcaFuB7lRpf/2v4orPKjWocYMqYxKOU0\n D65w==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20221208; t=1683796456; x=1686388456;\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=xajTdXEpezjJKaQbfSvApGR4iTAOWKtfCvREQginYZg=;\n b=T81qHgzWZSaV/V7Cc1iTC9QptnyUmq+/UekMT9NChpEFqAsAWiyvkG4044CGD3/zH/\n zvsVhB+gad6WXkvlnFzR7+4baahmhhseNIb6jcOh5lpvv53ZXuy4xRvY8/zQYcyWGDVz\n 6WEyEjp2K8401LqfM58t5Td+HvjuedAHfzAl8z+R01miNzB/RlMPCYmLTiIvJzoUEnxz\n EhleohZUV8FL4959iP7s/ruxzywnhlRcUPndY5De++GNbsEqH/0rr16kZFIfLw0o8Eld\n zd+2jk5wVOihQO6FQVh2NT28dDFzZF30MyZaBMciTqnDt4v4P4ZAF4yiub7X/RLs8zhQ\n R9rg==", "X-Gm-Message-State": "AC+VfDy2ikL4kQlwdXSqp5XYTC2ebkvlIjfQyBBLmPZLDcCpKE1uZ0XI\n zNuL9L5MQeRiRFA+iedTOvZTAw==", "X-Google-Smtp-Source": "\n ACHHUZ6yYgHEdrIb8m6tSq7OfNISBq9KZ5wvtg7pTK5IPkPqNC6NiNNLN+ajf8TlDMueurE7tuvCEA==", "X-Received": "by 2002:a17:907:7212:b0:966:61b3:f630 with SMTP id\n dr18-20020a170907721200b0096661b3f630mr13445588ejc.9.1683796456522;\n Thu, 11 May 2023 02:14:16 -0700 (PDT)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, lijuan.tu@intel.com,\n bruce.richardson@intel.com, wathsala.vithanage@arm.com,\n jspewock@iol.unh.edu, probb@iol.unh.edu", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[RFC PATCH v3 3/4] dts: add doc generation", "Date": "Thu, 11 May 2023 11:14:07 +0200", "Message-Id": "<20230511091408.236638-4-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.30.2", "In-Reply-To": "<20230511091408.236638-1-juraj.linkes@pantheon.tech>", "References": "<20230504123749.1417259-1-juraj.linkes@pantheon.tech>\n <20230511091408.236638-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 configuration is kept the same to preserve the style.\n\nSphinx generates the documentation from Python docstrings. The docstring\nformat most suitable for DTS seems to be the Google format [0] which\nrequires the sphinx.ext.napoleon extension.\n\nThere are two requirements for building DTS docs:\n* The same Python version as DTS or higher, because Sphinx import 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 | 22 ++++++++++----\n doc/guides/meson.build | 1 +\n doc/guides/tools/dts.rst | 29 +++++++++++++++++++\n dts/doc/doc-index.rst | 20 +++++++++++++\n dts/doc/meson.build | 51 +++++++++++++++++++++++++++++++++\n dts/meson.build | 16 +++++++++++\n meson.build | 1 +\n meson_options.txt | 2 ++\n 10 files changed, 157 insertions(+), 15 deletions(-)\n create mode 100644 dts/doc/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 2876a78a7e..1f0c725a94 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 a55ce38800..3f11cbc8fc 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,19 @@\n file=stderr)\n pass\n \n+extensions = ['sphinx.ext.napoleon']\n+\n+# Python docstring options\n+autodoc_member_order = 'bysource'\n+autodoc_typehints = 'both'\n+autodoc_typehints_format = 'short'\n+napoleon_numpy_docstring = False\n+napoleon_attr_annotations = True\n+napoleon_use_ivar = True\n+napoleon_use_rtype = False\n+add_module_names = False\n+toc_object_entries_show_parents = 'hide'\n+\n stop_on_error = ('-W' in argv)\n \n project = 'Data Plane Development Kit'\n@@ -35,8 +47,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 ebd6dceb6a..a547da2017 100644\n--- a/doc/guides/tools/dts.rst\n+++ b/doc/guides/tools/dts.rst\n@@ -282,3 +282,32 @@ 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 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+\n+Build commands\n+~~~~~~~~~~~~~~\n+\n+The documentation is built using the standard DPDK build system.\n+\n+After 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.\ndiff --git a/dts/doc/doc-index.rst b/dts/doc/doc-index.rst\nnew file mode 100644\nindex 0000000000..10151c6851\n--- /dev/null\n+++ b/dts/doc/doc-index.rst\n@@ -0,0 +1,20 @@\n+.. DPDK Test Suite documentation master file, created by\n+ sphinx-quickstart on Tue Mar 14 12:23:52 2023.\n+ You can adapt this file completely to your liking, but it should at least\n+ contain the root `toctree` directive.\n+\n+Welcome to DPDK Test Suite's documentation!\n+===========================================\n+\n+.. toctree::\n+ :maxdepth: 4\n+ :caption: Contents:\n+\n+ modules\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..8c1416296b\n--- /dev/null\n+++ b/dts/doc/meson.build\n@@ -0,0 +1,51 @@\n+# SPDX-License-Identifier: BSD-3-Clause\n+# Copyright(c) 2023 PANTHEON.tech s.r.o.\n+\n+sphinx = find_program('sphinx-build', required: get_option('enable_dts_docs'))\n+sphinx_apidoc = find_program('sphinx-apidoc', required: get_option('enable_dts_docs'))\n+\n+if sphinx.found() and sphinx_apidoc.found()\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',\n+ '--doc-project', 'DTS', '-V', meson.project_version(),\n+ '-o', dts_api_build_dir,\n+ dts_api_framework_dir],\n+ build_by_default: get_option('enable_dts_docs'))\n+doc_targets += dts_api_src\n+doc_target_names += 'DTS_API_sphinx_sources'\n+\n+cp = find_program('cp', required: get_option('enable_dts_docs'))\n+cp_index = custom_target('cp_index',\n+ input: 'doc-index.rst',\n+ output: 'index.rst',\n+ depends: dts_api_src,\n+ command: [cp, '@INPUT@', join_paths(dts_api_build_dir, 'index.rst')],\n+ build_by_default: get_option('enable_dts_docs'))\n+doc_targets += cp_index\n+doc_target_names += 'DTS_API_sphinx_index'\n+\n+extra_sphinx_args = ['-a', '-c', doc_guides_source_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: ['DTS_ROOT=@0@'.format(dts_dir),\n+ sphinx_wrapper, sphinx, meson.project_version(),\n+ dts_api_build_dir, dts_api_build_dir,\n+ '--dts-root', dts_dir, extra_sphinx_args],\n+ build_by_default: get_option('enable_dts_docs'),\n+ install: get_option('enable_dts_docs'),\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..17bda07636\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 f91d652bc5..7820f334bb 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -84,6 +84,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\ndiff --git a/meson_options.txt b/meson_options.txt\nindex 82c8297065..267f1b3ef7 100644\n--- a/meson_options.txt\n+++ b/meson_options.txt\n@@ -16,6 +16,8 @@ option('drivers_install_subdir', type: 'string', value: 'dpdk/pmds-<VERSION>', d\n 'Subdirectory of libdir where to install PMDs. Defaults to using a versioned subdirectory.')\n option('enable_docs', type: 'boolean', value: false, description:\n 'build documentation')\n+option('enable_dts_docs', type: 'boolean', value: false, description:\n+ 'Build DTS API documentation.')\n option('enable_apps', type: 'string', value: '', description:\n 'Comma-separated list of apps to build. If unspecified, build all apps.')\n option('enable_drivers', type: 'string', value: '', description:\n", "prefixes": [ "RFC", "v3", "3/4" ] }