Message ID | 20240806111756.314055-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 74FD44574A; Tue, 6 Aug 2024 13:17:59 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 3EE8042DC5; Tue, 6 Aug 2024 13:17:59 +0200 (CEST) Received: from mail-ed1-f42.google.com (mail-ed1-f42.google.com [209.85.208.42]) by mails.dpdk.org (Postfix) with ESMTP id AD2F1402A1 for <dev@dpdk.org>; Tue, 6 Aug 2024 13:17:57 +0200 (CEST) Received: by mail-ed1-f42.google.com with SMTP id 4fb4d7f45d1cf-5af51684d52so534463a12.1 for <dev@dpdk.org>; Tue, 06 Aug 2024 04:17:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722943077; x=1723547877; 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=gXsimzhcS6Ur44po/S/BFh5Fzl9CTfaBckV/j8JFfV8=; b=GYDYljEtZ1ztfhJNlhxbUaUPUNW/F2tAsXux3+iUXRZYlQzz9/VPbFrOB2a//2RadM gluqUTpAEF+cTf68gauxkWLEUzYMJPbWSv4gQwe3Gk1VIbA9R59iV/OYrPEBbsBfTpAq NAG35hYGizodi035SFXokLD7vasHBDlR3dKpDScFi9rqjA043W6mkKfWJgMqh0xPujoR Qo4ZuBw3UY/DECQMOEbNS/y5hv/w3GcLl8j9CxAzXD/EfKiEVXAGPo2ONc4C78EnPKWV enPt+32meJ3MoPGaHUvsN9LbP55/cJLyhg103ptXYG6CtrwGULcQ1H4jIw/7hLd97j1T rRpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722943077; x=1723547877; 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=gXsimzhcS6Ur44po/S/BFh5Fzl9CTfaBckV/j8JFfV8=; b=fJID3+UXuCiNCGx3CxYapYnAEZtMO92SyXWZTdmob4zZFmYO2LltXhq3QtxbrJq5tf 10sUEEpQGuAnchV+Mw+ileawMfVuAGBIx/2nFcK2c79Y1n6aOk7IUoilIo9soLrtcCS2 A0ifQTN9uj/ArejT+W03xbHpPU05MHl9VBupS/HC/e7lhrLt06h366VgGk1QH3rc6h8Z WYe6vowNIjwslS/anRtHuK6pzt4Jzmj2ljxNP9JewiUIJaiq5dP/9TflL7rUofV6G+nY PLx1XFQqksEYrV6VK8WzMm/MHkrnqfpWRSRhEXx4+C4aL2c7WQBwn6eDzOsADu8RdG2m vYeA== X-Gm-Message-State: AOJu0YzPbR0jVRlnozWvzTk8ch32glEjlxY7fxkXG+saayGQmkH4H60y JLTugmrUHCf/+2RT+2iKDuEWALMwx3AEo9eHEt62pIzcsa8ajB5vzlJemsBIa+A= X-Google-Smtp-Source: AGHT+IFdktZg0I7r4Tue7mtVhUUus5TKJY7eMAORzsO7jWK7BsvSFpYZRk04bE8q9WCtPyJ14iwSSA== X-Received: by 2002:aa7:cc01:0:b0:5b4:fa3c:d9ab with SMTP id 4fb4d7f45d1cf-5b7f5129408mr9986399a12.23.1722943077169; Tue, 06 Aug 2024 04:17:57 -0700 (PDT) Received: from jlinkes-PT-Latitude-5530.pantheon.local (81.89.53.154.host.vnet.sk. [81.89.53.154]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5bb885c8b57sm2624520a12.96.2024.08.06.04.17.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 06 Aug 2024 04:17:56 -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 v14 0/6] API docs generation Date: Tue, 6 Aug 2024 13:17:50 +0200 Message-Id: <20240806111756.314055-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 |
API docs generation
|
|
Message
Juraj Linkeš
Aug. 6, 2024, 11:17 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. 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 <meson_build_dir> -Denable_docs=true ninja -C <meson_build_dir> The above will do a full DPDK build with docs. To build just docs: meson setup <meson_build_dir> 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. 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. v12: Added paramiko to the required dependencies of get-dts-deps.py. v13: Fixed build error: TypeError: unsupported operand type(s) for |: 'NoneType' and 'Transport' v14: Fixed install error: ERROR: File 'dts/doc/html' could not be found This required me to put the built docs into dts/doc which is outside the DPDK API doc dir, resulting in linking between DPDK and DTS api docs not working properly. I addressed this by adding a symlink to the build dir. This way the link works after installing the docs and the symlink is just one extra file in the build dir. Juraj Linkeš (6): dts: update params and parser docstrings dts: replace the or operator in third party types 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 | 43 ++ dts/framework/params/__init__.py | 4 +- dts/framework/params/eal.py | 7 +- dts/framework/params/types.py | 3 +- dts/framework/parser.py | 4 +- .../interactive_remote_session.py | 3 +- dts/meson.build | 15 + dts/poetry.lock | 521 +++++++++++++++++- dts/pyproject.toml | 8 + meson.build | 1 + 59 files changed, 1086 insertions(+), 26 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