From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <dev-bounces@dpdk.org> Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id B157A454E2; Mon, 24 Jun 2024 16:25:50 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E5F8340E16; Mon, 24 Jun 2024 16:25:48 +0200 (CEST) Received: from mail-lj1-f172.google.com (mail-lj1-f172.google.com [209.85.208.172]) by mails.dpdk.org (Postfix) with ESMTP id 29D97402F0 for <dev@dpdk.org>; Mon, 24 Jun 2024 16:25:47 +0200 (CEST) Received: by mail-lj1-f172.google.com with SMTP id 38308e7fff4ca-2ec58040f39so19528371fa.2 for <dev@dpdk.org>; Mon, 24 Jun 2024 07:25:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1719239146; x=1719843946; 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=wmPyOl5QrJTCngIYwLd5lxdMWjiR0YVlZamb7w1F5R0=; b=flkHoUTr8vqZRclfLghERgv5IWj9vyVPOEZoA0lG1deCnv9Q2k3kUD7VJGdJxEhoY2 hp5i4PvAh77RLauM05lw9HybSZ9DxyvHPfJkeUuh6TrsGbk9XJihhYU9xsOXy4fGrrwp NcdKnve42Vug9zOZQjZapfL1FzAUIFtkQl1gAMiNlVZDxQvfA2PYKqQAdvlRg48VVSX9 pS04UMwjjud6GdnFVfVRFIH2ytvPJkm2OhGxLuDxSI4Ol8omk9YZHFPMEb2nIQXVI/pt vskbE0rcIBRjx3WnhOqqi07mKXTMx68Oj7jv64znUn8eVGs0gPPDZgWanG0u1YO0/HKn aeSQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719239146; x=1719843946; 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=wmPyOl5QrJTCngIYwLd5lxdMWjiR0YVlZamb7w1F5R0=; b=b01zM0Sj7cozOALmhy2jt5Y72xIob9X9t/cgoFkgOvQjWHMHPe6lleqTgGN8QrGzU0 4s7s0eTvYJP++Vn+G6R9RXNJaQkfmkgScpvVzeNiuN9chWRZvGMbfSPFYfrixHf2SBv5 x5R7ZA5DKnExdZZvT0woyVJtLJAbN+xAo7TqF/QHp6tqE2y2gYergDE0reVIIhSwoX65 SrYqYDnxPE/sufeWUXq6BpKV0LiNqUzNb40It66Ll5j773TPVdcDWsVjgXGPghbUFA84 tW2QjQy3skG5CD1Ql+V+J5upUzmMQtQgBiMtYRl8o5Xi/m+cJL3XF7AJLYS8X1QVdkaj AEJA== X-Gm-Message-State: AOJu0YwsRspQk6+0BQhHR2gQlQZ0CltgoOdHQo//4E7TJ/qYlo51CPT1 KzrHKnZ/2dB1ufpazCe52gIQFgcPHcBIPgyncJ4sH3qfhTYe8kZhuUXYWO06EJY= X-Google-Smtp-Source: AGHT+IENKI+MaIChVF9ntdT18N8C1SQoNXunqrCBcVbaenrR1NKaxOK4K4z2hTR2K/pXcqRwomaaWg== X-Received: by 2002:ac2:4eca:0:b0:52c:cc38:592c with SMTP id 2adb3069b0e04-52ce05f8bf9mr3034302e87.0.1719239146439; Mon, 24 Jun 2024 07:25:46 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a72521c9514sm136964566b.6.2024.06.24.07.25.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 24 Jun 2024 07:25:46 -0700 (PDT) From: =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech> 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=20Linke=C5=A1?= <juraj.linkes@pantheon.tech> Subject: [PATCH v7 0/4] dts: API docs generation Date: Mon, 24 Jun 2024 16:25:40 +0200 Message-Id: <20240624142544.35644-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>, <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>, <mailto:dev-request@dpdk.org?subject=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 <meson_build_dir> 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. 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. v5: Another rebase, but this time the rebase needed the addition of .rst corresponding to newly added files as well as fixing a few documentation problems in said files. v6: Documentation formatting adjustments. v7: Now with the actual doc changes. Juraj Linkeš (4): dts: update params and parser docstrings dts: add doc generation dependencies dts: add API doc sources dts: add API doc generation buildtools/call-sphinx-build.py | 31 +- 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 + dts/doc/framework.params.eal.rst | 6 + dts/doc/framework.params.rst | 14 + dts/doc/framework.params.testpmd.rst | 6 + dts/doc/framework.params.types.rst | 6 + dts/doc/framework.parser.rst | 6 + .../framework.remote_session.dpdk_shell.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 | 18 + .../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 | 43 ++ dts/doc/meson.build | 27 + dts/framework/params/__init__.py | 4 +- dts/framework/params/eal.py | 7 +- dts/framework/params/types.py | 3 +- dts/framework/parser.py | 4 +- dts/meson.build | 16 + dts/poetry.lock | 510 +++++++++++++++++- dts/pyproject.toml | 7 + meson.build | 1 + 54 files changed, 977 insertions(+), 37 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.params.eal.rst create mode 100644 dts/doc/framework.params.rst create mode 100644 dts/doc/framework.params.testpmd.rst create mode 100644 dts/doc/framework.params.types.rst create mode 100644 dts/doc/framework.parser.rst create mode 100644 dts/doc/framework.remote_session.dpdk_shell.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 -- 2.34.1