Message ID | 20240801093740.237929-1-juraj.linkes@pantheon.tech (mailing list archive) |
---|---|
Headers |
Return-Path: <dev-bounces@dpdk.org> 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 927634570F; Thu, 1 Aug 2024 11:37:44 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 8572C40A7F; Thu, 1 Aug 2024 11:37:44 +0200 (CEST) Received: from mail-ej1-f52.google.com (mail-ej1-f52.google.com [209.85.218.52]) by mails.dpdk.org (Postfix) with ESMTP id 36F56402C8 for <dev@dpdk.org>; Thu, 1 Aug 2024 11:37:43 +0200 (CEST) Received: by mail-ej1-f52.google.com with SMTP id a640c23a62f3a-a7d89bb07e7so377597866b.3 for <dev@dpdk.org>; Thu, 01 Aug 2024 02:37:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722505062; x=1723109862; 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=e6pyoVDr0TVy8OVKxiw/hSpUy6QCPOEoFI1GnFtfp9w=; b=A3ZArGGywdG88oxn97lHcO8JJTlgW9yjVRxVxGS40GN7Wk1DFlcOI09ZdU9QgeIpoD o4CNuoghId3qf+k2TDYaVA8Sm6aC+2+YLjShBcV7Lx5Z5ygH92thouy9AeyDTYfxZfkp qsXCf7n1A4LUFvsUxwtbMsQacABdAvQmvJcV5uHJOsuGJbw7W0CAsi1XRpJe4w2oliXQ 2GuhVxQwDbOHIROMQghTeAEyZrLwkBzKK9bnlRRSrPIOnor20z8HMG0eow66ATwo6NZt GLnY6U+UVIHeBrDeaHRyGciaGDk53ouJ2sa5HWe6gf2KanQ18EZ1A4MqGZilBPWMah8Y TsVg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722505062; x=1723109862; 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=e6pyoVDr0TVy8OVKxiw/hSpUy6QCPOEoFI1GnFtfp9w=; b=ROtmjHnhJfvvJDia5Ag4aXDv/3k9uRXT5zgQ75OcKpriWtWVGTNXBWv0zOIk0gMqIP mBF0d0NzxwYbHCd/Zro27Jfbmk3yMEtH8+zsYM4BtNehKwa/f0BksvajCWxPiMwXsJ6U OhnUSMBrGKt2wcK+CoP7F2cPQSyr+B0ETHDULUjK49s9EvhNrD53RnigQQtUxy/Sv6V5 LrM5voogDSaUXKMtkxWULiii9SQ5EH7IuNHZ73l91qm8z00czLxFtbR+BduJgdu/Jd1q wpHVgeYf434AsfClOibayE2GPNNv7Ptq19BUU1pRqbqMEAU5tZ4X3JsEBylJVKJATlLS jZYg== X-Gm-Message-State: AOJu0Yzw/EI7yZhz9KN+h/T2IEsq7aGX8Evr1tE5L4QJ+Gff2HSSSGuV 0VPYlqEJv2LrQphsllXq+QSIM+CzvtZCOhHjUIdfzImwB0XKYFa5Fn3xgaFEORM= X-Google-Smtp-Source: AGHT+IEUrGWNtDe9ZxjCguSbBuXbKmxduM9cGUjpM/M1Z3f/Jng9hMFuNyHwwj2pUcR9cDyDArwh/A== X-Received: by 2002:a17:906:f592:b0:a7a:afe8:1020 with SMTP id a640c23a62f3a-a7daf57a411mr155630566b.31.1722505062370; Thu, 01 Aug 2024 02:37:42 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a7acab236eesm869742266b.22.2024.08.01.02.37.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Aug 2024 02:37:42 -0700 (PDT) From: =?utf-8?q?Juraj_Linke=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_Linke=C5=A1?= <juraj.linkes@pantheon.tech> Subject: [PATCH v10 0/5] dts: API docs generation Date: Thu, 1 Aug 2024 11:37:35 +0200 Message-Id: <20240801093740.237929-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 |
Series | dts: API docs generation | |
Message
Juraj Linkeš
Aug. 1, 2024, 9:37 a.m. UTC
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. v8: Split the last commit into non-DTS and DTS changes. v9: Rebase. v10: Fix dts doc generation issue: Only copy the custom rss file if it exists. 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 | 37 +- 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, 980 insertions(+), 40 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