From patchwork Fri Apr 12 10:14:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Juraj_Linke=C5=A1?= X-Patchwork-Id: 856 Return-Path: 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]) by inbox.dpdk.org (Postfix) with ESMTP id 080A043E51; Fri, 12 Apr 2024 12:14:11 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E9961402A2; Fri, 12 Apr 2024 12:14:10 +0200 (CEST) Received: from mail-ej1-f48.google.com (mail-ej1-f48.google.com [209.85.218.48]) by mails.dpdk.org (Postfix) with ESMTP id DDEAD400D6 for ; Fri, 12 Apr 2024 12:14:08 +0200 (CEST) Received: by mail-ej1-f48.google.com with SMTP id a640c23a62f3a-a51969e780eso96481366b.3 for ; Fri, 12 Apr 2024 03:14:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1712916847; x=1713521647; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=dLFHRVsTlws97nG60bd7xljTw0C1ruqq++v2FWAh97w=; b=prKJVBuv4ZqvIabJLF5ZqSilidFCgRYf6HkXplJ3z4Mius4CGQv6aSSgndUYoM/PfF 1xoGwe0Eg4DVGvgclkmLBV1zyuxsrnV4xPaklPetXp3x7cSEkg1dTewqNdKOXcHr59N3 Z2XWdiPJQH/Wj7kwP8xss6xIqD0oy/WA38SRvnyDCVWBMvuMh7QRV8QYpFK4/Cmg56YI r724FsnHVXBF5xcGdx/3tktnqr/604gf8rY9bzgmLMW/Vhq+zd2y2nHhdabGXl/dVRCT 6pOo9bAr4Hfygl5mn8xt3I9/uVPWw9EPitxp8EKarnLIYXWVl9zzy0P4d+YaEoSTfylh +fNA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1712916847; x=1713521647; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=dLFHRVsTlws97nG60bd7xljTw0C1ruqq++v2FWAh97w=; b=qedugYSHsczjw7BDVBuxT27BbaQJSJU1vhi5JWiJs67X0hCSivZiOneVLkpc2BH4FB OVN8L8PTMWlJ34v3nJKHK9w3dQyRYSwDWyXUcZ+BWM0TxwliGAl5vPrB+7oBeNbTaDDH jTHEzfJJX8W156spWdkus6ZA8nMt56ST7HUMZXQPL1/6ns4P3gmFZWvsljea5lWaIAhC JrIi8hCohSyKCYTIapscpnTyrXcxiwzD8fBxvWK/PmY8yWsrU6nE5lgxU1QjjQFuM94V 7NW+dtwDfE9HOhCj+C5brYg+5JssmSq7bAtCuFgvGoWAJPg+r8ycNBvA78Iabuac77Bw bgcw== X-Gm-Message-State: AOJu0YxBrVczE2HWbZJ6MwjU9AaltJn/mXiTr1y9E8t4qjdTbTIcSO8+ mIV/u8Bwwk8lJA75b8LttO4JeJD5B1C1IdMnPAWq0GLprYEXg9p0wmB6tbl13UU= X-Google-Smtp-Source: AGHT+IGAQsPU+023lpDJDKJJGsNyme7yi//uOqN4VI8BGgaWhbiPdr3XU6474Dx+fvNXaur+B1dBiA== X-Received: by 2002:a17:907:972a:b0:a51:827d:c99b with SMTP id jg42-20020a170907972a00b00a51827dc99bmr1675100ejc.14.1712916847638; Fri, 12 Apr 2024 03:14:07 -0700 (PDT) Received: from jlinkes-PT-Latitude-5530.pantheon.local ([84.245.121.75]) by smtp.gmail.com with ESMTPSA id k11-20020a170906578b00b00a51be2b75f3sm1640802ejq.35.2024.04.12.03.14.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 12 Apr 2024 03:14:07 -0700 (PDT) From: =?utf-8?q?Juraj_Linke=C5=A1?= To: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu Cc: dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= 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 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org The generation is done with Sphinx, which DPDK already uses, with slightly modified configuration of the sidebar present in an if block. Dependencies are installed using Poetry from the dts directory: poetry install --with docs After installing, enter the Poetry shell: poetry shell And then run the build: ninja -C dts-doc Python3.10 is required to build the DTS API docs. The patchset contains the .rst sources which Sphinx uses to generate the html pages. These were first generated with the sphinx-apidoc utility and modified to provide a better look. The documentation just doesn't look that good without the modifications and there isn't enough configuration options to achieve that without manual changes to the .rst files. This introduces extra maintenance which involves adding new .rst files when a new Python module is added or changing the .rst structure if the Python directory/file structure is changed (moved, renamed files). This small maintenance burden is outweighed by the flexibility afforded by the ability to make manual changes to the .rst files. We can merge this patch when: 1. We agree on the approach with manually modifying the files. This approach is, in my opinion, much better than just generating the .rst files every time, 2. Bruce sends his ack on the meson modifications. I believe we had a positive reaction on the previous version, but not this one. 3. The link to DTS API docs that was added to doxy-api-index.md is satisfactory. I think Thomas could check this? v2: Removed the use of sphinx-apidoc from meson in favor of adding the files generated by it directly to the repository (and modifying them). v3: Rebase. v4: Rebase. Juraj Linkeš (3): dts: add doc generation dependencies dts: add API doc sources dts: add API doc generation buildtools/call-sphinx-build.py | 33 +- doc/api/doxy-api-index.md | 3 + doc/api/doxy-api.conf.in | 2 + doc/api/meson.build | 11 +- doc/guides/conf.py | 39 +- doc/guides/meson.build | 1 + doc/guides/tools/dts.rst | 34 +- dts/doc/conf_yaml_schema.json | 1 + dts/doc/framework.config.rst | 12 + dts/doc/framework.config.types.rst | 6 + dts/doc/framework.exception.rst | 6 + dts/doc/framework.logger.rst | 6 + ...ote_session.interactive_remote_session.rst | 6 + ...ework.remote_session.interactive_shell.rst | 6 + .../framework.remote_session.python_shell.rst | 6 + ...ramework.remote_session.remote_session.rst | 6 + dts/doc/framework.remote_session.rst | 17 + .../framework.remote_session.ssh_session.rst | 6 + ...framework.remote_session.testpmd_shell.rst | 6 + dts/doc/framework.runner.rst | 6 + dts/doc/framework.settings.rst | 6 + dts/doc/framework.test_result.rst | 6 + dts/doc/framework.test_suite.rst | 6 + dts/doc/framework.testbed_model.cpu.rst | 6 + .../framework.testbed_model.linux_session.rst | 6 + dts/doc/framework.testbed_model.node.rst | 6 + .../framework.testbed_model.os_session.rst | 6 + dts/doc/framework.testbed_model.port.rst | 6 + .../framework.testbed_model.posix_session.rst | 6 + dts/doc/framework.testbed_model.rst | 26 + dts/doc/framework.testbed_model.sut_node.rst | 6 + dts/doc/framework.testbed_model.tg_node.rst | 6 + ..._generator.capturing_traffic_generator.rst | 6 + ...mework.testbed_model.traffic_generator.rst | 14 + ....testbed_model.traffic_generator.scapy.rst | 6 + ...el.traffic_generator.traffic_generator.rst | 6 + ...framework.testbed_model.virtual_device.rst | 6 + dts/doc/framework.utils.rst | 6 + dts/doc/index.rst | 41 ++ dts/doc/meson.build | 27 + dts/meson.build | 16 + dts/poetry.lock | 499 +++++++++++++++++- dts/pyproject.toml | 7 + meson.build | 1 + 44 files changed, 920 insertions(+), 20 deletions(-) create mode 120000 dts/doc/conf_yaml_schema.json create mode 100644 dts/doc/framework.config.rst create mode 100644 dts/doc/framework.config.types.rst create mode 100644 dts/doc/framework.exception.rst create mode 100644 dts/doc/framework.logger.rst create mode 100644 dts/doc/framework.remote_session.interactive_remote_session.rst create mode 100644 dts/doc/framework.remote_session.interactive_shell.rst create mode 100644 dts/doc/framework.remote_session.python_shell.rst create mode 100644 dts/doc/framework.remote_session.remote_session.rst create mode 100644 dts/doc/framework.remote_session.rst create mode 100644 dts/doc/framework.remote_session.ssh_session.rst create mode 100644 dts/doc/framework.remote_session.testpmd_shell.rst create mode 100644 dts/doc/framework.runner.rst create mode 100644 dts/doc/framework.settings.rst create mode 100644 dts/doc/framework.test_result.rst create mode 100644 dts/doc/framework.test_suite.rst create mode 100644 dts/doc/framework.testbed_model.cpu.rst create mode 100644 dts/doc/framework.testbed_model.linux_session.rst create mode 100644 dts/doc/framework.testbed_model.node.rst create mode 100644 dts/doc/framework.testbed_model.os_session.rst create mode 100644 dts/doc/framework.testbed_model.port.rst create mode 100644 dts/doc/framework.testbed_model.posix_session.rst create mode 100644 dts/doc/framework.testbed_model.rst create mode 100644 dts/doc/framework.testbed_model.sut_node.rst create mode 100644 dts/doc/framework.testbed_model.tg_node.rst create mode 100644 dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst create mode 100644 dts/doc/framework.testbed_model.traffic_generator.rst create mode 100644 dts/doc/framework.testbed_model.traffic_generator.scapy.rst create mode 100644 dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst create mode 100644 dts/doc/framework.testbed_model.virtual_device.rst create mode 100644 dts/doc/framework.utils.rst create mode 100644 dts/doc/index.rst create mode 100644 dts/doc/meson.build create mode 100644 dts/meson.build