Cover Detail
Show a cover letter.
GET /api/covers/856/?format=api
{ "id": 856, "url": "http://patches.dpdk.org/api/covers/856/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/cover/20240412101405.94377-1-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-1-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20240412101405.94377-1-juraj.linkes@pantheon.tech", "date": "2024-04-12T10:14:02", "name": "[v4,0/3] dts: API docs generation", "submitter": { "id": 1626, "url": "http://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "mbox": "http://patches.dpdk.org/project/dpdk/cover/20240412101405.94377-1-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/covers/856/comments/", "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 080A043E51;\n\tFri, 12 Apr 2024 12:14:11 +0200 (CEST)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id E9961402A2;\n\tFri, 12 Apr 2024 12:14:10 +0200 (CEST)", "from mail-ej1-f48.google.com (mail-ej1-f48.google.com\n [209.85.218.48]) by mails.dpdk.org (Postfix) with ESMTP id DDEAD400D6\n for <dev@dpdk.org>; Fri, 12 Apr 2024 12:14:08 +0200 (CEST)", "by mail-ej1-f48.google.com with SMTP id\n a640c23a62f3a-a51969e780eso96481366b.3\n for <dev@dpdk.org>; Fri, 12 Apr 2024 03:14:08 -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.06\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Fri, 12 Apr 2024 03:14:07 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1712916847; x=1713521647; 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=dLFHRVsTlws97nG60bd7xljTw0C1ruqq++v2FWAh97w=;\n b=prKJVBuv4ZqvIabJLF5ZqSilidFCgRYf6HkXplJ3z4Mius4CGQv6aSSgndUYoM/PfF\n 1xoGwe0Eg4DVGvgclkmLBV1zyuxsrnV4xPaklPetXp3x7cSEkg1dTewqNdKOXcHr59N3\n Z2XWdiPJQH/Wj7kwP8xss6xIqD0oy/WA38SRvnyDCVWBMvuMh7QRV8QYpFK4/Cmg56YI\n r724FsnHVXBF5xcGdx/3tktnqr/604gf8rY9bzgmLMW/Vhq+zd2y2nHhdabGXl/dVRCT\n 6pOo9bAr4Hfygl5mn8xt3I9/uVPWw9EPitxp8EKarnLIYXWVl9zzy0P4d+YaEoSTfylh\n +fNA==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1712916847; x=1713521647;\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=dLFHRVsTlws97nG60bd7xljTw0C1ruqq++v2FWAh97w=;\n b=qedugYSHsczjw7BDVBuxT27BbaQJSJU1vhi5JWiJs67X0hCSivZiOneVLkpc2BH4FB\n OVN8L8PTMWlJ34v3nJKHK9w3dQyRYSwDWyXUcZ+BWM0TxwliGAl5vPrB+7oBeNbTaDDH\n jTHEzfJJX8W156spWdkus6ZA8nMt56ST7HUMZXQPL1/6ns4P3gmFZWvsljea5lWaIAhC\n JrIi8hCohSyKCYTIapscpnTyrXcxiwzD8fBxvWK/PmY8yWsrU6nE5lgxU1QjjQFuM94V\n 7NW+dtwDfE9HOhCj+C5brYg+5JssmSq7bAtCuFgvGoWAJPg+r8ycNBvA78Iabuac77Bw\n bgcw==", "X-Gm-Message-State": "AOJu0YxBrVczE2HWbZJ6MwjU9AaltJn/mXiTr1y9E8t4qjdTbTIcSO8+\n mIV/u8Bwwk8lJA75b8LttO4JeJD5B1C1IdMnPAWq0GLprYEXg9p0wmB6tbl13UU=", "X-Google-Smtp-Source": "\n AGHT+IGAQsPU+023lpDJDKJJGsNyme7yi//uOqN4VI8BGgaWhbiPdr3XU6474Dx+fvNXaur+B1dBiA==", "X-Received": "by 2002:a17:907:972a:b0:a51:827d:c99b with SMTP id\n jg42-20020a170907972a00b00a51827dc99bmr1675100ejc.14.1712916847638;\n Fri, 12 Apr 2024 03:14:07 -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 0/3] dts: API docs generation", "Date": "Fri, 12 Apr 2024 12:14:02 +0200", "Message-Id": "<20240412101405.94377-1-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231115133606.42081-1-juraj.linkes@pantheon.tech>", "References": "<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 generation is done with Sphinx, which DPDK already uses, with\nslightly modified configuration of the sidebar present in an if block.\n\nDependencies are installed using Poetry from the dts directory:\n\npoetry install --with docs\n\nAfter installing, enter the Poetry shell:\n\npoetry shell\n\nAnd then run the build:\nninja -C <meson_build_dir> dts-doc\n\nPython3.10 is required to build the DTS API docs.\n\nThe patchset contains the .rst sources which Sphinx uses to generate the\nhtml pages. These were first generated with the sphinx-apidoc utility\nand modified to provide a better look. The documentation just doesn't\nlook that good without the modifications and there isn't enough\nconfiguration options to achieve that without manual changes to the .rst\nfiles. This introduces extra maintenance which involves adding new .rst\nfiles when a new Python module is added or changing the .rst structure\nif the Python directory/file structure is changed (moved, renamed\nfiles). This small maintenance burden is outweighed by the flexibility\nafforded by the ability to make manual changes to the .rst files.\n\nWe can merge this patch when:\n1. We agree on the approach with manually modifying the files.\nThis approach is, in my opinion, much better than just generating the\n.rst files every time,\n2. Bruce sends his ack on the meson modifications. I believe we had a\npositive reaction on the previous version, but not this one.\n3. The link to DTS API docs that was added to doxy-api-index.md is\nsatisfactory. I think Thomas could check this?\n\nv2:\nRemoved the use of sphinx-apidoc from meson in favor of adding the files\ngenerated by it directly to the repository (and modifying them).\n\nv3:\nRebase.\n\nv4:\nRebase.\n\nJuraj Linkeš (3):\n dts: add doc generation dependencies\n dts: add API doc sources\n dts: add API doc generation\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/conf_yaml_schema.json | 1 +\n dts/doc/framework.config.rst | 12 +\n dts/doc/framework.config.types.rst | 6 +\n dts/doc/framework.exception.rst | 6 +\n dts/doc/framework.logger.rst | 6 +\n ...ote_session.interactive_remote_session.rst | 6 +\n ...ework.remote_session.interactive_shell.rst | 6 +\n .../framework.remote_session.python_shell.rst | 6 +\n ...ramework.remote_session.remote_session.rst | 6 +\n dts/doc/framework.remote_session.rst | 17 +\n .../framework.remote_session.ssh_session.rst | 6 +\n ...framework.remote_session.testpmd_shell.rst | 6 +\n dts/doc/framework.runner.rst | 6 +\n dts/doc/framework.settings.rst | 6 +\n dts/doc/framework.test_result.rst | 6 +\n dts/doc/framework.test_suite.rst | 6 +\n dts/doc/framework.testbed_model.cpu.rst | 6 +\n .../framework.testbed_model.linux_session.rst | 6 +\n dts/doc/framework.testbed_model.node.rst | 6 +\n .../framework.testbed_model.os_session.rst | 6 +\n dts/doc/framework.testbed_model.port.rst | 6 +\n .../framework.testbed_model.posix_session.rst | 6 +\n dts/doc/framework.testbed_model.rst | 26 +\n dts/doc/framework.testbed_model.sut_node.rst | 6 +\n dts/doc/framework.testbed_model.tg_node.rst | 6 +\n ..._generator.capturing_traffic_generator.rst | 6 +\n ...mework.testbed_model.traffic_generator.rst | 14 +\n ....testbed_model.traffic_generator.scapy.rst | 6 +\n ...el.traffic_generator.traffic_generator.rst | 6 +\n ...framework.testbed_model.virtual_device.rst | 6 +\n dts/doc/framework.utils.rst | 6 +\n dts/doc/index.rst | 41 ++\n dts/doc/meson.build | 27 +\n dts/meson.build | 16 +\n dts/poetry.lock | 499 +++++++++++++++++-\n dts/pyproject.toml | 7 +\n meson.build | 1 +\n 44 files changed, 920 insertions(+), 20 deletions(-)\n create mode 120000 dts/doc/conf_yaml_schema.json\n create mode 100644 dts/doc/framework.config.rst\n create mode 100644 dts/doc/framework.config.types.rst\n create mode 100644 dts/doc/framework.exception.rst\n create mode 100644 dts/doc/framework.logger.rst\n create mode 100644 dts/doc/framework.remote_session.interactive_remote_session.rst\n create mode 100644 dts/doc/framework.remote_session.interactive_shell.rst\n create mode 100644 dts/doc/framework.remote_session.python_shell.rst\n create mode 100644 dts/doc/framework.remote_session.remote_session.rst\n create mode 100644 dts/doc/framework.remote_session.rst\n create mode 100644 dts/doc/framework.remote_session.ssh_session.rst\n create mode 100644 dts/doc/framework.remote_session.testpmd_shell.rst\n create mode 100644 dts/doc/framework.runner.rst\n create mode 100644 dts/doc/framework.settings.rst\n create mode 100644 dts/doc/framework.test_result.rst\n create mode 100644 dts/doc/framework.test_suite.rst\n create mode 100644 dts/doc/framework.testbed_model.cpu.rst\n create mode 100644 dts/doc/framework.testbed_model.linux_session.rst\n create mode 100644 dts/doc/framework.testbed_model.node.rst\n create mode 100644 dts/doc/framework.testbed_model.os_session.rst\n create mode 100644 dts/doc/framework.testbed_model.port.rst\n create mode 100644 dts/doc/framework.testbed_model.posix_session.rst\n create mode 100644 dts/doc/framework.testbed_model.rst\n create mode 100644 dts/doc/framework.testbed_model.sut_node.rst\n create mode 100644 dts/doc/framework.testbed_model.tg_node.rst\n create mode 100644 dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst\n create mode 100644 dts/doc/framework.testbed_model.traffic_generator.rst\n create mode 100644 dts/doc/framework.testbed_model.traffic_generator.scapy.rst\n create mode 100644 dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst\n create mode 100644 dts/doc/framework.testbed_model.virtual_device.rst\n create mode 100644 dts/doc/framework.utils.rst\n create mode 100644 dts/doc/index.rst\n create mode 100644 dts/doc/meson.build\n create mode 100644 dts/meson.build" }