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 5914E454E1; Mon, 24 Jun 2024 15:46:05 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 322244029C; Mon, 24 Jun 2024 15:46:05 +0200 (CEST) Received: from mail-ej1-f50.google.com (mail-ej1-f50.google.com [209.85.218.50]) by mails.dpdk.org (Postfix) with ESMTP id 4FFE04026E for ; Mon, 24 Jun 2024 15:46:03 +0200 (CEST) Received: by mail-ej1-f50.google.com with SMTP id a640c23a62f3a-a725041ad74so61944966b.3 for ; Mon, 24 Jun 2024 06:46:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1719236763; x=1719841563; 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=T1fe+Y1Q5Ch7rE0IaguqPxyEfOYc8DJPZMqWXZ5IWAw=; b=k7C24kkOpwuoBg2+8RwtnxFASxFE7UI6DKoAVvO8qXe7iE4xP+Vh4lReCxN48FKZ3W pgFHqvxZcz9J+mMpM6wAkv6XXdI1GeYoIPBFy358Q63vusemc3q9alMPwE3mM1ef98D3 bSlZ6uU2WoxRNhLcwrJtcMKc/Dtvu0uS/iIuJk0s98AnUpcdV/dLRwaN1xHq9nhebaJi ltBGDubA/jH/A0EwYZWMbqyXjfg2z7Udoq/NwsRB8296uzky0ah5yY6v+FlAUcPPsY6J +f2Dubzv94DWTp6mq/xwD5dcUdfoiSKPRN2ymclupwB84SIYwV+PELFnSnE9PrZpLwOo 8kTQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719236763; x=1719841563; 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=T1fe+Y1Q5Ch7rE0IaguqPxyEfOYc8DJPZMqWXZ5IWAw=; b=B7/T3FXBl0755bdcMZ9c2rcaUftP9T8gjSSCAcZEbl7h7VSjkhtHx2Yp2y87WjhjXI wn9m5cYPWMxNJw4zjMqi6MTcNXORq0X5y4R0hd7F63Tx6ziqojx24/ZPD5AoAkgMs5ol 02RAlV6Ttn6dVV9mBbALIMDrD5gLocyz7l3oC/zC2TXKmPCJ9B7rVR7W+BjOUlC5B15Q d0Nmjhtaf2zGr4J86Q6tW3L6lP+j1fiaPwbZ9SoFjk0mVTzr/EQVjLlgSUA/tRLVQGIt FfeHhm7gPbxiEkVVg3UNj1zkspuXE6WOHugw8Q8xC2mauFfOqNeKm0NhaqcglZzJN5g/ EtBw== X-Gm-Message-State: AOJu0YyJy9Jsp7rgW6hVObeFHVoEt88ydfUVE3bzfm9xV20DVxXWqHGp G7Z6Qetrig2wgtdO2L7ei/Ly0N7Wu4nvr1Bl7NDxIZM9ABSlVeNUeItL44HU8a8= X-Google-Smtp-Source: AGHT+IHQM+O3dntfuZRquPrIr7oTQMiNJ6vHOdsBWqEwYEJXCdd6xNLaWbX+G/4+euFHkQ+YH8JXtg== X-Received: by 2002:aa7:c403:0:b0:57d:55a2:73f1 with SMTP id 4fb4d7f45d1cf-57d55a2748fmr2437741a12.34.1719236762966; Mon, 24 Jun 2024 06:46:02 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-57d3041208esm4716383a12.30.2024.06.24.06.46.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 24 Jun 2024 06:46:02 -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 v6 0/4] dts: API docs generation Date: Mon, 24 Jun 2024 15:45:56 +0200 Message-Id: <20240624134600.31500-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. Juraj Linkeš (4): dts: update params and parser docstrings dts: add doc generation dependencies dts: add API doc sources dts: add API doc generation 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