Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/134400/?format=api
{ "id": 134400, "url": "http://patches.dpdk.org/api/patches/134400/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20231115133606.42081-3-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": "<20231115133606.42081-3-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231115133606.42081-3-juraj.linkes@pantheon.tech", "date": "2023-11-15T13:36:06", "name": "[v1,2/2] dts: add doc generation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "b1ca7a01055707ab4ed76d4679f755b7b6272d81", "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/20231115133606.42081-3-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30303, "url": "http://patches.dpdk.org/api/series/30303/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30303", "date": "2023-11-15T13:36:04", "name": "dts: api docs generation", "version": 1, "mbox": "http://patches.dpdk.org/series/30303/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/134400/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/134400/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 5019743339;\n\tWed, 15 Nov 2023 14:36:24 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 8708540DDC;\n\tWed, 15 Nov 2023 14:36:13 +0100 (CET)", "from mail-ed1-f51.google.com (mail-ed1-f51.google.com\n [209.85.208.51]) by mails.dpdk.org (Postfix) with ESMTP id 4D9C440A70\n for <dev@dpdk.org>; Wed, 15 Nov 2023 14:36:11 +0100 (CET)", "by mail-ed1-f51.google.com with SMTP id\n 4fb4d7f45d1cf-543923af573so10520042a12.0\n for <dev@dpdk.org>; Wed, 15 Nov 2023 05:36:11 -0800 (PST)", "from jlinkes-PT-Latitude-5530.pantheon.local\n (81.89.53.154.host.vnet.sk. [81.89.53.154])\n by smtp.gmail.com with ESMTPSA id\n n20-20020a170906b31400b009e656ce2930sm7100749ejz.60.2023.11.15.05.36.09\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Wed, 15 Nov 2023 05:36:09 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1700055371; x=1700660171; 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=NPUVgPJM8TmlpRlcy1Les52Eifz6NcfeoEfent6G3TY=;\n b=HpjJU8qNJlvHZszHl5qEcTbb64o62bMCsVbi4Ytps0VJIk/zsMCiVLQ2QQMciakmOm\n BjMBosV0s/K0mYvsniuH1jDjeAkWrFht3aUvSCU68wnFoURlONPOmtOlsxm0QpOntjpN\n JbgFNMBWb/CIGpR6TLg9FZ5tuVEcc8DGKJjs99t/g1FC5fuF3FEaXIRep4xSlBcvCQ5r\n JeJlDUdfAHeZl+4HgLco8B2p7Nwd0PKRWocY8uKfR7ab+Yba6X8pW/FCY05srAGcX8Af\n SEWC3oged3eSC9Uv2EZrTTiafyRDHLBrS5zTrrkrm0fJHZBqLbKZJ70AlS8KR4B+XOKj\n RMLg==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1700055371; x=1700660171;\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=NPUVgPJM8TmlpRlcy1Les52Eifz6NcfeoEfent6G3TY=;\n b=V2gPnBKJQoFvKXiCfHQP/wP8qF4huYc7/Q/1MqddMQlxtNaqpxi1jxBcmwXDROmqI3\n Z/uYUJAlJsN83co+cXc4fjLXZXNkEyDrBJCmThp6rsfnTqQj3uQ6ZgU1oqhaJNEIuwpe\n vHfBh0oMzGH5g29adPPykKlO68JrvE/RXiaPKBNkN3Jw7GmAS1pXQmTj0ExN/0XdAScb\n TuR185JDOMxYFkub2AgacL8FiHcAOPy0o57VjTxYQ6bsoFuOBK8xt2FlctDmoqY8DyR3\n McCLQNS0fjyjIA/QbasofCNt54Lqp+pWbZEJs3Z5vfIXUtiEUppZgkgVOUlRU7ztMmo3\n uvKw==", "X-Gm-Message-State": "AOJu0YxhqKjbOoYoQf8YJRudrK0eAOue58r9NJ7n6LnD5wjrutyyJNBz\n BAGQz7yMQZjbb4ditd9/tHzpUw==", "X-Google-Smtp-Source": "\n AGHT+IERWbTaAGVK3Anu2uTkIxn7I2W3hZX2MIgVbnIwh82fmHPn7f24LAMLxoo1Ha0rnWhN1W/NiA==", "X-Received": "by 2002:a17:906:3794:b0:9ae:522e:8f78 with SMTP id\n n20-20020a170906379400b009ae522e8f78mr7661387ejc.74.1700055370969;\n Wed, 15 Nov 2023 05:36:10 -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 v1 2/2] dts: add doc generation", "Date": "Wed, 15 Nov 2023 14:36:06 +0100", "Message-Id": "<20231115133606.42081-3-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231115133606.42081-1-juraj.linkes@pantheon.tech>", "References": "<20231108125324.191005-23-juraj.linkes@pantheon.tech>\n <20231115133606.42081-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 | 60 +++++++++++++++++++++++++++++++++\n dts/meson.build | 16 +++++++++\n meson.build | 1 +\n 10 files changed, 176 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 cd771a428c..77d9434c1c 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..e11ab83843\n--- /dev/null\n+++ b/dts/doc/meson.build\n@@ -0,0 +1,60 @@\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_api_framework_dir = join_paths(dts_dir, 'framework')\n+dts_api_build_dir = join_paths(doc_api_build_dir, 'dts')\n+if meson.version().version_compare('>=0.57.0')\n+ dts_api_src = custom_target('dts_api_src',\n+ output: 'modules.rst',\n+ env: {'SPHINX_APIDOC_OPTIONS': 'members,show-inheritance'},\n+ command: [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+else\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+endif\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 5e161f43e5..001fdcbbbf 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": [ "v1", "2/2" ] }