Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/139236/?format=api
{ "id": 139236, "url": "http://patches.dpdk.org/api/patches/139236/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20240412101405.94377-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": "<20240412101405.94377-4-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20240412101405.94377-4-juraj.linkes@pantheon.tech", "date": "2024-04-12T10:14:05", "name": "[v4,3/3] dts: add API doc generation", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "588ab84e59e43322f4a3a3c3c669125449489cf6", "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/20240412101405.94377-4-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 31728, "url": "http://patches.dpdk.org/api/series/31728/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=31728", "date": "2024-04-12T10:14:02", "name": "dts: API docs generation", "version": 4, "mbox": "http://patches.dpdk.org/series/31728/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/139236/comments/", "check": "fail", "checks": "http://patches.dpdk.org/api/patches/139236/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 A5EA243E51;\n\tFri, 12 Apr 2024 12:14:33 +0200 (CEST)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 6DABA40A76;\n\tFri, 12 Apr 2024 12:14:15 +0200 (CEST)", "from mail-lf1-f54.google.com (mail-lf1-f54.google.com\n [209.85.167.54]) by mails.dpdk.org (Postfix) with ESMTP id 9668D406BC\n for <dev@dpdk.org>; Fri, 12 Apr 2024 12:14:12 +0200 (CEST)", "by mail-lf1-f54.google.com with SMTP id\n 2adb3069b0e04-516d47ce662so1146456e87.1\n for <dev@dpdk.org>; Fri, 12 Apr 2024 03:14:12 -0700 (PDT)", "from jlinkes-PT-Latitude-5530.pantheon.local ([84.245.121.75])\n by smtp.gmail.com with ESMTPSA id\n k11-20020a170906578b00b00a51be2b75f3sm1640802ejq.35.2024.04.12.03.14.10\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Fri, 12 Apr 2024 03:14:11 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1712916852; x=1713521652; 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=0fT4rFTx5S2snWFzvDXZDIgiH/T0bh2PnzsPQGA9zEY=;\n b=gFKvkiSaDDceIP4B3bN+bWE2rgGHWOhSwjMiGpBp/NKQzvJ0aq1wAozUgGD8GADzLG\n wGiY12/gC6WpS7By6TYZFeQavrgmV+uboMZWj9/BujxIYPAf4TEKYgoN5tXOV2nisAmz\n A4B/MSeUaY+j+pAJcfzcvnHH260waPpzw7jbhZ8S3TxLoeiw7KHUSM1Ccv/tl2Q+qrnT\n ZYpfoNQyR+/fzxDmCSXDbcVN1g3ezY+xavdOS9G4JkrMbxH8d/6qJGKrGXfQnlr3383x\n ajyGKXUbMpUTsqNiy0TDjwP/5id4CEUnb22lYrBL0MQZnaeP5HY4ikE3TSv1mANobUbl\n RVKQ==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1712916852; x=1713521652;\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=0fT4rFTx5S2snWFzvDXZDIgiH/T0bh2PnzsPQGA9zEY=;\n b=GyknQfc60P513lzEXjK6hE/AMZHrp5gpTPPMA998/XeW4i9vcgW5uoc20TlE/TprIO\n YmwLv+6Lbd3x89dBoyZwsBCoSQQhQTIlUnpm89s5qbVEC3JSfYaWJ4biFqf9zal+sqn3\n pyInzZixTUR+1Eo/M8Ufn/5wMLnQkqmLINs6+K5sHn2mOW01J6SqDo38MU0aMyYKbq2C\n B1pQs97RSqOAepob/NQcdE95PTtYecFmvem56UW8HSniwls2ouKjRuX5IGOIMrx6KIDE\n JaG8Onh6NauC/MOm5cvzS8ioinxwWNNqVlSCoJC2UtAKLr+M3aELoPFSeDwMHEKPQObX\n gbOQ==", "X-Gm-Message-State": "AOJu0Yz30Urp5IHSB8JkEwcJv3AmzvZ2LJMaaomBAS0Rc70rNQbI6SYo\n Rt9/Mxb7fENpufjKFEdiVlGZ9h0RPLGvQPalH4xJVlAxxb7LmT/LywUwatkEHbY=", "X-Google-Smtp-Source": "\n AGHT+IGX6s7lxpvnC/KQhmzcDdaLnmXryl79y9p2YrqAmAXUUUTblRZoYBpjesOGNeBFnQ/XtDC9Rw==", "X-Received": "by 2002:a05:6512:3d11:b0:518:9844:648d with SMTP id\n d17-20020a0565123d1100b005189844648dmr51850lfv.60.1712916851956;\n Fri, 12 Apr 2024 03:14:11 -0700 (PDT)", "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, Luca.Vizzarro@arm.com, npratte@iol.unh.edu", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v4 3/3] dts: add API doc generation", "Date": "Fri, 12 Apr 2024 12:14:05 +0200", "Message-Id": "<20240412101405.94377-4-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20240412101405.94377-1-juraj.linkes@pantheon.tech>", "References": "<20231115133606.42081-1-juraj.linkes@pantheon.tech>\n <20240412101405.94377-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 DTS API docs is Sphinx, which is already in\nuse in DPDK. The same configuration is used to preserve style with one\nDTS-specific configuration (so that the DPDK docs are unchanged) that\nmodifies how the sidebar displays the content.\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>\nReviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>\nTested-by: Nicholas Pratte <npratte@iol.unh.edu>\n---\n buildtools/call-sphinx-build.py | 33 +++++++++++++++++++---------\n doc/api/doxy-api-index.md | 3 +++\n doc/api/doxy-api.conf.in | 2 ++\n doc/api/meson.build | 11 +++++++---\n doc/guides/conf.py | 39 ++++++++++++++++++++++++++++-----\n doc/guides/meson.build | 1 +\n doc/guides/tools/dts.rst | 34 +++++++++++++++++++++++++++-\n dts/doc/meson.build | 27 +++++++++++++++++++++++\n dts/meson.build | 16 ++++++++++++++\n meson.build | 1 +\n 10 files changed, 148 insertions(+), 19 deletions(-)\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..aea771a64e 100755\n--- a/buildtools/call-sphinx-build.py\n+++ b/buildtools/call-sphinx-build.py\n@@ -3,37 +3,50 @@\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=None)\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+if args.dts_root:\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+if not os.path.exists(args.dst):\n+ os.makedirs(args.dst)\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/doxy-api-index.md b/doc/api/doxy-api-index.md\nindex 8c1eb8fafa..d5f823b7f0 100644\n--- a/doc/api/doxy-api-index.md\n+++ b/doc/api/doxy-api-index.md\n@@ -243,3 +243,6 @@ The public API headers are grouped by topics:\n [experimental APIs](@ref rte_compat.h),\n [ABI versioning](@ref rte_function_versioning.h),\n [version](@ref rte_version.h)\n+\n+- **tests**:\n+ [**DTS**](@dts_api_main_page)\ndiff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in\nindex 27afec8b3b..2e08c6a452 100644\n--- a/doc/api/doxy-api.conf.in\n+++ b/doc/api/doxy-api.conf.in\n@@ -123,6 +123,8 @@ SEARCHENGINE = YES\n SORT_MEMBER_DOCS = NO\n SOURCE_BROWSER = YES\n \n+ALIASES = \"dts_api_main_page=@DTS_API_MAIN_PAGE@\"\n+\n EXAMPLE_PATH = @TOPDIR@/examples\n EXAMPLE_PATTERNS = *.c\n EXAMPLE_RECURSIVE = YES\ndiff --git a/doc/api/meson.build b/doc/api/meson.build\nindex 5b50692df9..ffc75d7b5a 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()\n@@ -32,14 +33,18 @@ example = custom_target('examples.dox',\n # set up common Doxygen configuration\n cdata = configuration_data()\n cdata.set('VERSION', meson.project_version())\n-cdata.set('API_EXAMPLES', join_paths(dpdk_build_root, 'doc', 'api', 'examples.dox'))\n-cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))\n+cdata.set('API_EXAMPLES', join_paths(doc_api_build_dir, 'examples.dox'))\n+cdata.set('OUTPUT', doc_api_build_dir)\n cdata.set('TOPDIR', dpdk_source_root)\n-cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))\n+cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, doc_api_build_dir]))\n cdata.set('WARN_AS_ERROR', 'NO')\n if get_option('werror')\n cdata.set('WARN_AS_ERROR', 'YES')\n endif\n+# A local reference must be relative to the main index.html page\n+# The path below can't be taken from the DTS meson file as that would\n+# require recursive subdir traversal (doc, dts, then doc again)\n+cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html'))\n \n # configure HTML Doxygen run\n html_cdata = configuration_data()\ndiff --git a/doc/guides/conf.py b/doc/guides/conf.py\nindex 0f7ff5282d..b442a1f76c 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,37 @@\n file=stderr)\n pass\n \n+# Napoleon enables the Google format of Python doscstrings, used in DTS\n+# Intersphinx allows linking to external projects, such as Python docs, also used in DTS\n+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.intersphinx']\n+\n+# DTS 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 = True\n+toc_object_entries_show_parents = 'hide'\n+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}\n+\n+dts_root = environ.get('DTS_ROOT')\n+if dts_root:\n+ path.append(dts_root)\n+ # DTS 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 +65,7 @@\n html_show_copyright = False\n highlight_language = 'none'\n \n-release = environ.setdefault('DPDK_VERSION', \"None\")\n-version = release\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 47b218b2c6..d1c3c2af7a 100644\n--- a/doc/guides/tools/dts.rst\n+++ b/doc/guides/tools/dts.rst\n@@ -280,7 +280,12 @@ and try not to divert much from it.\n The :ref:`DTS developer tools <dts_dev_tools>` will issue warnings\n when some of the basics are not met.\n \n-The code must be properly documented with docstrings.\n+The API documentation, which is a helpful reference when developing, may be accessed\n+in the code directly or generated with the :ref:`API docs build steps <building_api_docs>`.\n+When adding new files or modifying the directory structure, the corresponding changes must\n+be made to DTS api doc sources in ``dts/doc``.\n+\n+Speaking of which, the code must be properly documented with docstrings.\n The style must conform to the `Google style\n <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.\n See an example of the style `here\n@@ -415,6 +420,33 @@ 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 --no-root --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.\n+\n+\n Configuration Schema\n --------------------\n \ndiff --git a/dts/doc/meson.build b/dts/doc/meson.build\nnew file mode 100644\nindex 0000000000..01b7b51034\n--- /dev/null\n+++ b/dts/doc/meson.build\n@@ -0,0 +1,27 @@\n+# SPDX-License-Identifier: BSD-3-Clause\n+# Copyright(c) 2023 PANTHEON.tech s.r.o.\n+\n+sphinx = find_program('sphinx-build', required: false)\n+sphinx_apidoc = find_program('sphinx-apidoc', required: false)\n+\n+if not sphinx.found() or not sphinx_apidoc.found()\n+ subdir_done()\n+endif\n+\n+dts_doc_api_build_dir = join_paths(doc_api_build_dir, 'dts')\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', 'dts')\n+dts_api_html = custom_target('dts_api_html',\n+ output: 'html',\n+ command: [sphinx_wrapper, sphinx, meson.project_version(),\n+ meson.current_source_dir(), dts_doc_api_build_dir, extra_sphinx_args],\n+ build_by_default: false,\n+ install: get_option('enable_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..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 8b248d4505..835973a0ce 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": [ "v4", "3/3" ] }