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 E399045741; Mon, 5 Aug 2024 16:00:03 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 670F4402E6; Mon, 5 Aug 2024 16:00:03 +0200 (CEST) Received: from mail-ed1-f53.google.com (mail-ed1-f53.google.com [209.85.208.53]) by mails.dpdk.org (Postfix) with ESMTP id 11822402B7 for ; Mon, 5 Aug 2024 16:00:02 +0200 (CEST) Received: by mail-ed1-f53.google.com with SMTP id 4fb4d7f45d1cf-5a1c496335aso7568717a12.1 for ; Mon, 05 Aug 2024 07:00:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722866401; x=1723471201; 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=mfq1aqczOguv1x1AoMcjdWE+/Qo/er1NPcuBDR2qpVk=; b=UBGWvUiy6X8MGhoa5uZqXWAN2z6rujOBCJ/qhgyArJiWq8gL+rHjLEobEkapkgAf5a kvfuHggTR4z6qheS8O3DTxAye8I7ycFfuze70M77riapv/xBU5O5/w2z0IRyLwV0u6GN 1t/Dnou3XgbC4pgHEeDoOtz+XjpzJaoea5WN4NMPlBnVnrzUjsFyKNv85g1+2mOR6bY9 TEKUhRu+XamwFhA4Vf17ZzSzvH6vyPSJUndOQWaQYsEH6kiceAAJOBTzX53Lkx83nmmR ASmSeg1SdjloCv/gDKK4kRnGf/S1301tCSrT1QdHKTVv9a5eyQ8J4S2sXpK7Eruu+d0B fRWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722866401; x=1723471201; 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=mfq1aqczOguv1x1AoMcjdWE+/Qo/er1NPcuBDR2qpVk=; b=qiVWV/+j9Kd9rFByMDwG634HyZyz0s+pHpN3KY+HtRucgvaH1LNnbb7/jirB6CXEp2 s46Qae9EY6HCN7ijAOYO+ssXyMASwyeFQTLNjq0tWVBwaKSn/MqQrUqkOL6pVEXC+qH8 vct+rcaUEX1ANjXO+Mz4RkkAkhUGf+FNk471b8ztAFcXEsyaGgb9upzYfMn1uArVdCE4 YhlfjvivsJFp0pxAspaClBLWcdaT4pNSpVNrqnYC5wQwo1r0fokJzfkS4ACnvF6CfDU2 L6lmDC+0yjn0FMVpXBJNkPXTGJGjtJ/aJx2IDfhGpod5ZeX0zkO4/TcU0WkkES5woXVm zOZw== X-Gm-Message-State: AOJu0YwUy03n7E3IjLkr0h5GFlJTP4kaTjiZdSdb7LpilgTCBJnK9dQ5 Fr885lCisNUnnv4cpuilqj5gNw4EKZRzOGsWlxQGlHcNAZ/QQ0BpDJ4vwdkiT8M= X-Google-Smtp-Source: AGHT+IHbEUqtDfPqeSDC8Z0QgMNVvXq910RLG6xcHL4yMruY37Iqkmc9vUQ+yH6TZTbOTZxiFTDaug== X-Received: by 2002:aa7:d357:0:b0:5a0:e303:8f0f with SMTP id 4fb4d7f45d1cf-5b7f39e042fmr10528807a12.10.1722866401434; Mon, 05 Aug 2024 07:00:01 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5b839b2b556sm4939230a12.25.2024.08.05.07.00.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 05 Aug 2024 07:00:01 -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 v11 0/5] dts: API docs generation Date: Mon, 5 Aug 2024 15:59:54 +0200 Message-Id: <20240805135959.214457-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. 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. 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. 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. 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 -- 2.34.1