From patchwork Mon Jan 22 16:35:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Juraj_Linke=C5=A1?= X-Patchwork-Id: 572 Return-Path: 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 1C61C4399B; Mon, 22 Jan 2024 17:35:13 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D035A402C9; Mon, 22 Jan 2024 17:35:12 +0100 (CET) Received: from mail-lf1-f52.google.com (mail-lf1-f52.google.com [209.85.167.52]) by mails.dpdk.org (Postfix) with ESMTP id CDAC0402C3 for ; Mon, 22 Jan 2024 17:35:11 +0100 (CET) Received: by mail-lf1-f52.google.com with SMTP id 2adb3069b0e04-50e7f58c5fbso3993574e87.1 for ; Mon, 22 Jan 2024 08:35:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1705941311; x=1706546111; 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=8P7cpg3ViSnMzHq2FXna/7VfZ127pM7sPmJRylp1RAY=; b=J+uNFyzaiLcvbwoAn2Tg9KFcUr489NpDGfcA637G14q7Hv62EAUhsd7eMTbI4U1GJB 1UZ5UAlkXurtM7bI4sA7VHv2JHCthzpWhsx4liM3wtXL6Xz4O4ETl/+JFR222PFZ2Cqw YCpdeYwxDT0P8Q//M6SwPphPB0/MBoBj5SdCNhCf8x8InyvhCevok6TtGvJp4AVBBd8C +qMfFBhxH/FVZS+0fpWOH+hPjXGxTKDGj89wPnFTV3ESlB6L21vMZ4BANLz8tgQ2GBRO LN/z+M7niDy1AWvnvGDPTvHEiQ4xKjrGf77u2e9ZlkWdAo9oTS1kBPHwoWIaiUxXVhEK 2i+g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705941311; x=1706546111; 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=8P7cpg3ViSnMzHq2FXna/7VfZ127pM7sPmJRylp1RAY=; b=l8YyEgGvjLBwU9vsRD5aXw7ycVjdSJsTDDbN+epd6tC/xI++9XilO1O7xEG+4misxP KEYAcZA6eVuZFxFMSasXE3AoH8G238g40UYwNPGSLRVA3FOzAYKzLc2VwBv4e8oNpdnn rbgqRyNYdCGM7L3LQNt7mAQHVOLsP4o+50YplOSwDjuwVk0LBUberwU5cSEvgE76H0Aq Ek+fF6nhy+fza96bq2BfG2rjCeA/3S7nypQBL2muaLgEnITzkeBpTvbOqi6JE9LfzftV KW3UtOCyrpjgA58qe9S5g1LfLl1RoQXw+gLW+lDZbXbhzOexdLEQcoOkPcIIrnYp+87B a9Pg== X-Gm-Message-State: AOJu0YxD3kFc3xSVKTWlj/iiYqWRtE9Kswa8DF8poN8RreiFgQm9ZLDi iwR0rcydrbwdkOlkex/AvvE+PgM5Qz/MJA3MGxGHqUoCFWzs1LbUUHVGGWi9VYE= X-Google-Smtp-Source: AGHT+IE6PtOcDV4u/XdZXDA4MrDECCgrNXWJU1LooQ9RGPhEH3QJ7BN8DAzMzHNHYEcXMKxVil1JmA== X-Received: by 2002:a05:6512:3994:b0:50e:76eb:ba14 with SMTP id j20-20020a056512399400b0050e76ebba14mr2539106lfu.32.1705941311235; Mon, 22 Jan 2024 08:35:11 -0800 (PST) Received: from localhost.localdomain ([84.245.120.159]) by smtp.gmail.com with ESMTPSA id q14-20020a1709060f8e00b00a2a61b9c166sm13475878ejj.33.2024.01.22.08.35.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 22 Jan 2024 08:35:10 -0800 (PST) From: =?utf-8?q?Juraj_Linke=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, yoan.picchi@foss.arm.com, Luca.Vizzarro@arm.com Cc: dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= Subject: [PATCH v3 0/3] dts: API docs generation Date: Mon, 22 Jan 2024 17:35:06 +0100 Message-Id: <20240122163509.22385-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 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 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. 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