From patchwork Tue Aug 6 06:13:56 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: 1199 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 8B91B45748; Tue, 6 Aug 2024 08:14:05 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 75F81402CF; Tue, 6 Aug 2024 08:14:05 +0200 (CEST) Received: from mail-ej1-f43.google.com (mail-ej1-f43.google.com [209.85.218.43]) by mails.dpdk.org (Postfix) with ESMTP id 8ED65402BA for ; Tue, 6 Aug 2024 08:14:04 +0200 (CEST) Received: by mail-ej1-f43.google.com with SMTP id a640c23a62f3a-a7aa212c1c9so39780466b.2 for ; Mon, 05 Aug 2024 23:14:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722924844; x=1723529644; 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=vACBqL07DmQoTxtn2BdRlUEDO3y7aIO6+J/5R6YRQ1U=; b=sOdRgk2o7Xo3Z/8+Z/MF7c2UimTqErWY7Pp0gN2sfafyReMJ6HbjTHVZSzBiMsdTrB xNWFo3sDJUxniJvuY+N3phLB+qA60MuJcjo9y1kvC7mU6Y92Bz3+uUOgUxx0IZoYyq6I ocvkaFHAfjHaIeAqj6Y0M07Msj3HNJFJO+GTHasTq7nLV8Nk+47K6/A34k9yQ9TrFpMk 3jTwTMPYynXuZ9KEZQcqjJYeZa/bwh7jQ3K32UYGcVM/MCOtWt6RDdwsanpxWxlrzEtZ kSklxlsAveUSm1fhj8en5ED1s2F+zaUFjb34SOdvxB+riLvkZxOwpTNIWkqu5XoXP9rl HbWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722924844; x=1723529644; 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=vACBqL07DmQoTxtn2BdRlUEDO3y7aIO6+J/5R6YRQ1U=; b=DjYXoQoy98ED+FrTR2WNM4AptK3J1TaRQAt+k3GhM37wsouxl4n5LoalnbulC3rEc4 HBWBzHuYuzCAlF3AR5vrzH1VxmSdW5pnGgbovgC08K7cLbdBDz5eCqCSYjM6Eys1guCi xJsVA0OrIqfN5Ko2PVILicq1shjzP1DwHXXisp3p65V1zeHs0cPYV/pil7EyY3g0EPMT bXJOuM7wAWGs2iyMeNRPxN4YKpTt8SLuLKW6EXcKuSYz/7KbRB8iVWbAQHZEekalm0l3 ushIgjLdBi/24cSazYUqpIjFIrXWCDOaa/B2J7tk5rvbjdRpO2THn/dJvzltvzOkRUam QXXA== X-Gm-Message-State: AOJu0YwJRWlL/jVxp/B5VNst7aEYfVoCtDHqporJSbc/kvgUZJErf8dR WI0emVW3NXqp7RO8gty2KzM/OAtuOfdJucHJpPgbC/u5jYlZuIP7iGz17kg0FkQ= X-Google-Smtp-Source: AGHT+IGDw6+knmMCCFKeGCrkGPlm5x/SqC7NWFK8g6wb2sFhwL1hcVbJzxl19Prj5mloPuUn+lZWkA== X-Received: by 2002:a17:906:d54e:b0:a6f:33d6:2d45 with SMTP id a640c23a62f3a-a7dc50ff838mr784429166b.60.1722924843860; Mon, 05 Aug 2024 23:14:03 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a7dc9d515fesm514951466b.107.2024.08.05.23.14.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 05 Aug 2024 23:14:03 -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 v12 0/5] dts: API docs generation Date: Tue, 6 Aug 2024 08:13:56 +0200 Message-Id: <20240806061401.222164-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. DTS dependencies do not need to be installed, but there is the option to install doc build dependencies with Poetry: poetry install --with docs The build itself may be run with: meson setup -Denable_docs=true ninja -C The above will do a full DPDK build with docs. To build just docs: meson setup 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. v10: Fix dts doc generation issue: Only copy the custom rss file if it exists. v11: Added the config option autodoc_mock_imports, which eliminates the need for DTS dependencies. Added a script that find out which imports need to be added to autodoc_mock_imports. The script also check the required Python version for building DTS docs. Removed tags from the two affected patches which will need to be reviewed again. v12: Added paramiko to the required dependencies of get-dts-deps.py. Juraj Linkeš (5): dts: update params and parser docstrings dts: add doc generation dependencies dts: add API doc sources doc: meson doc API build dir variable dts: add API doc generation buildtools/call-sphinx-build.py | 10 +- buildtools/get-dts-deps.py | 78 +++ buildtools/meson.build | 1 + doc/api/doxy-api-index.md | 3 + doc/api/doxy-api.conf.in | 2 + doc/api/meson.build | 8 +- doc/guides/conf.py | 41 +- doc/guides/contributing/documentation.rst | 2 + doc/guides/contributing/patches.rst | 4 + doc/guides/meson.build | 1 + doc/guides/tools/dts.rst | 39 +- 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 | 30 + 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 | 15 + dts/poetry.lock | 521 +++++++++++++++++- dts/pyproject.toml | 8 + meson.build | 1 + 58 files changed, 1071 insertions(+), 25 deletions(-) create mode 100755 buildtools/get-dts-deps.py 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