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