From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id A02CE4560F; Fri, 12 Jul 2024 10:57:29 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 3395A402B3; Fri, 12 Jul 2024 10:57:29 +0200 (CEST) Received: from mail-ej1-f44.google.com (mail-ej1-f44.google.com [209.85.218.44]) by mails.dpdk.org (Postfix) with ESMTP id E41B1402AE for ; Fri, 12 Jul 2024 10:57:27 +0200 (CEST) Received: by mail-ej1-f44.google.com with SMTP id a640c23a62f3a-a77cb7c106dso226036466b.1 for ; Fri, 12 Jul 2024 01:57:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1720774646; x=1721379446; 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=SE6JhVMd5eW1e/5ljSmS09HvrMLLKK08AcZqwKYz8Fs=; b=Tb71MNoJFErEWCEn6cI2NV68JvzKUC0nkYNBhRAPAgvOpuCK9WC2gcwCFkuyPR0x8U XAVzL6ss2y+Sx4Y5Xko+6XnU6akVOTXZX65NDmc8hvJWPzDXXot2DUhgBZrxGqD0vPuz gFuiDi7dAVl5kzCTQnpU0C7y+9RSyZJcWjOQxr1+SW9/P/P1MGFVzIgaUrMMvZ/22Nhs ujU/IgPB2SU/RpZ71ot5Cw0Ri+GOqEJCatUw6B2AGfyuwSnpQaL44HxwiROCKiJdelX8 Iow5QzwpR5b6bEKpgqYHvQk2Rg6JSyLgDxz1ZfjzEL61YtGMOnnYfTkCmIldJmiT1Vom PBPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1720774646; x=1721379446; 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=SE6JhVMd5eW1e/5ljSmS09HvrMLLKK08AcZqwKYz8Fs=; b=gDSB9sbQCWXlhdKlpXwpXkNzOloj7HsdWEqDwdRWoHBbSfhBVrin6MU+eAHbX07acZ 7Jqqz7ORRcYLw1SPtc1ZQPxhkEmrA+rvFDHUGm22+VG0eq73dhDDioTqbO9pdwdllXBc vrvj7pVnLH0YU//gacycchTzxzCRztNFOnQP21zncbdK0W0O5CloiXOGF0oqzRmjnzJE AGTM2EPsdCubP86PNoDK0HQjSmjgdc0szKFQ12Wks5upW2082F2lLYQdjD8qO4sHPRCJ PBfFTNN81CfV2vfP767R9bgV713CDK1fh9DcSwYEzNjwtVpzOT23qpJ/oO7+W4FU5CPd aHiw== X-Gm-Message-State: AOJu0YytmJa0lVKIWte8UO5dAYKnW9sO7NvVIsOtErKCwN++82yEXf1m I5mGVc6T8UV+c9qvNZX3K7UmYw7IU8vwCkHjd6xFUP+06zEmnxkcet8/jdMag2Q= X-Google-Smtp-Source: AGHT+IEmaFedaxSrJH3M57PMZt9Gy2RtUemhtbOpoZ6irW0Fqd97Eu+L79sAC9j/aKl3HfQV6lzbZw== X-Received: by 2002:a17:907:ea1:b0:a75:110d:fa53 with SMTP id a640c23a62f3a-a780b885565mr923633766b.49.1720774646629; Fri, 12 Jul 2024 01:57:26 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a780a7ff7bbsm327987166b.141.2024.07.12.01.57.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 12 Jul 2024 01:57:26 -0700 (PDT) From: =?UTF-8?q?Juraj=20Linke=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=20Linke=C5=A1?= Subject: [PATCH v8 0/5] dts: API docs generation Date: Fri, 12 Jul 2024 10:57:19 +0200 Message-Id: <20240712085724.21065-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 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. 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. v8: Split the last commit into non-DTS and DTS changes. Juraj Linkeš (5): dts: update params and parser docstrings dts: add doc generation dependencies dts: add API doc sources doc: guides and API meson improvements 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