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 AA96443928; Mon, 22 Jan 2024 13:00:51 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4F3544028B; Mon, 22 Jan 2024 13:00:51 +0100 (CET) Received: from mail-ej1-f46.google.com (mail-ej1-f46.google.com [209.85.218.46]) by mails.dpdk.org (Postfix) with ESMTP id DC5594025D for <dev@dpdk.org>; Mon, 22 Jan 2024 13:00:49 +0100 (CET) Received: by mail-ej1-f46.google.com with SMTP id a640c23a62f3a-a28a6cef709so298497466b.1 for <dev@dpdk.org>; Mon, 22 Jan 2024 04:00:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1705924849; x=1706529649; 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=4COLTi7LHlVolzrx9hliiOf9K5FRE97oXkuSkC5m9JY=; b=MiSV6fUb/woFF6F9OjwUiZYpCCetHZbg7U/NQ8UdkwN7f06ktKFVMoBunJPvh2kXwl SQSGtYsUBg4dLDIh6Z7A1R4Mm3sKerIG3hv5lFi5FfVqMa3miJaeTaJLXwexf1tl7hwj UAZjVnLG+Z2ocwsV0yaGDrwEKjobnAH/hh/6BrFl9xIBWBbaxYskywzY7T+PDeQfZnPD bIvBI1FsgqnOi5/DHXqGgKofOfE5eLT28L5sIQkpy8JBiQMqLsaGEtk2ZABFpgLVawGo h0gIf7Ua5tfpAtvESYcx41+4CePRNf1G1oxIKVsYKrO04NKLC33xxKmYv24cTk2LF//a ooFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705924849; x=1706529649; 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=4COLTi7LHlVolzrx9hliiOf9K5FRE97oXkuSkC5m9JY=; b=uiGEVfANTlMqJ59+LemZ67iy3vX/A18rY5RtfEBLUYgXGohCknXvm2/kLdrXwx8FKe 48FPi5mHQHMjDKPXrcCMYHTBZ9kbTI4obGenhOGkr9R81I1NcWSL8rwRLnVqP7wyplfF s1GQotd/FN0IFIFfEam0HbaGIvmMLyCZmHqmhCi2/BtDvbS1cFKWx9hHSAFHdP2YpjeW wMFUkExYdFs04ifHeAp1515Bc7YXA1iO/nF3IlqB8PuOux+TI8jRb5d0JXYPzDmVjB3+ Tu71/nLRmPVuVj6HdJR8uokJ+HPB4d6wCF4aHNleTl/kqgpuv1jKvaWwTs2iy45BE5TL 1Z8A== X-Gm-Message-State: AOJu0YzjfSrWfW+/cUUNp4zOJh5Gryq+c6g+7+0gQij8THELkfScOf5l 4Bx912EqLF+ikhzZJ6ysFYYdlrBjPqJ66OKBXJjQCKvtZ89aTcXGkwZz/ttBN8yD9UJw4GQjBUZ Ox1Q= X-Google-Smtp-Source: AGHT+IFdphlKityHCpGTlcNtYU1YVgNHO+CxG1y5g7w51L5TWqpcmbcvSNl/yxgBoz0+k+WarWcVXA== X-Received: by 2002:a17:906:6a27:b0:a2e:acd2:1fe1 with SMTP id qw39-20020a1709066a2700b00a2eacd21fe1mr2462806ejc.73.1705924849495; Mon, 22 Jan 2024 04:00:49 -0800 (PST) Received: from localhost.localdomain ([84.245.120.159]) by smtp.gmail.com with ESMTPSA id x15-20020a170906298f00b00a27e4d34455sm13191550eje.183.2024.01.22.04.00.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 22 Jan 2024 04:00:49 -0800 (PST) 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, yoan.picchi@foss.arm.com, Luca.Vizzarro@arm.com Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech> Subject: [PATCH v2 0/3] dts: API docs generation Date: Mon, 22 Jan 2024 13:00:44 +0100 Message-Id: <20240122120047.16447-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 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). Juraj Linkeš (3): dts: add doc generation dependencies dts: add API doc sources dts: add API doc generation buildtools/call-sphinx-build.py | 33 +- 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.dts.rst | 6 + dts/doc/framework.exception.rst | 6 + dts/doc/framework.logger.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 | 17 + .../framework.remote_session.ssh_session.rst | 6 + ...framework.remote_session.testpmd_shell.rst | 6 + dts/doc/framework.rst | 30 ++ 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 | 41 ++ dts/doc/meson.build | 27 + dts/meson.build | 16 + dts/poetry.lock | 499 +++++++++++++++++- dts/pyproject.toml | 7 + meson.build | 1 + 45 files changed, 950 insertions(+), 20 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.dts.rst create mode 100644 dts/doc/framework.exception.rst create mode 100644 dts/doc/framework.logger.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.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