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 0B37142A5D; Thu, 4 May 2023 14:38:23 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id AA19642D3B; Thu, 4 May 2023 14:38:00 +0200 (CEST) Received: from mail-ej1-f42.google.com (mail-ej1-f42.google.com [209.85.218.42]) by mails.dpdk.org (Postfix) with ESMTP id 420BA42BDA for ; Thu, 4 May 2023 14:37:58 +0200 (CEST) Received: by mail-ej1-f42.google.com with SMTP id a640c23a62f3a-94f6c285d92so73635266b.3 for ; Thu, 04 May 2023 05:37:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683203878; x=1685795878; 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=JILQBaZWyFe3DbMq5T2bjd1NReJZf+9IsHg8xbamQo8=; b=SVY8mqeHpv7ucVe8I9V2TIbVkWRkMBS5ESAMi/pg3X2et5mT29ZQVaXpd0hLNRR5ht zI8xm8IPpYABnuiLfcYNSHZ6L1/nH2QdXODFrYdQdJcZRGeDPp0Sq8tZhTgNPDB/6gfK 7ajP5ZhtLaYQxSaY7a7xuqyDDgFDDVaHQ94xi0M7I7gR4zg2bYCTVr52K3ctESbAyid1 9OlkKPIBHOc4fL0ndJvC7/iPgLyTsbPC7euB8cgwzgpLXm0XKeXkZeBzcmg0+ZX9Sva7 J54HusjlEOMl6BY189quSYmyvS717CgKXSr7jAhT49xmLyFOYq1jNJjEAbkwgwKds36t /JUg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683203878; x=1685795878; 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=JILQBaZWyFe3DbMq5T2bjd1NReJZf+9IsHg8xbamQo8=; b=hra16A6My15tYpI3EYsERi9scM/RdwsmNmGJ0FVaS7nsDFVtNN3lFRQNESEqZ1XlrW g3CjR8E3CEIynxZpgSAygern0rk6aOyIKMSsw3metqf8wE8qU5/B1Q8NbQbeXFQaYwSR Gx9x7zOWhbbT/uPg+kBy6KUaWkDVnuLG8JmNZ9P39tEDGtkAT6OIm49Vb1txa+aRhR9q GUHHlnFht59IA1nHBRP5l0koZ45puISSRWVjumRDNOvD5Ssj61EC8l71Ce4e3IhoQfPD JLwMGbH3s4psCMdVdbxM+hPek+5AdkKo+KYlrsQPrYQqtn3Uxdu+aiJlE6YUQ2io+KVI tiBw== X-Gm-Message-State: AC+VfDypWNrEbn8RM7aorER1dIGnWg6QUrs0GPOz/459VMMB91EgQrkZ t7p4z3i+hLKRRezljBDmcdKG1thiljeF4kR7J5g= X-Google-Smtp-Source: ACHHUZ47E0lceqRuMhWnxo6sYD/fjEz9v5osV3eOMbCcGRvRf6nuFA5rL+mwegSBQ0GRIzUO7moV1A== X-Received: by 2002:a17:906:ee87:b0:94e:5c28:1c19 with SMTP id wt7-20020a170906ee8700b0094e5c281c19mr6272335ejb.5.1683203877788; Thu, 04 May 2023 05:37:57 -0700 (PDT) Received: from localhost.localdomain (ip-46.34.246.203.o2inet.sk. [46.34.246.203]) by smtp.gmail.com with ESMTPSA id wz13-20020a170906fe4d00b00959c6b9dac8sm13679157ejb.197.2023.05.04.05.37.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 04 May 2023 05:37:57 -0700 (PDT) From: =?UTF-8?q?Juraj=20Linke=C5=A1?= To: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, lijuan.tu@intel.com, bruce.richardson@intel.com, wathsala.vithanage@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= Subject: [RFC PATCH v2 3/4] dts: add doc generation Date: Thu, 4 May 2023 14:37:48 +0200 Message-Id: <20230504123749.1417259-4-juraj.linkes@pantheon.tech> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230504123749.1417259-1-juraj.linkes@pantheon.tech> References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-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 tool used to generate developer docs is sphinx, which is already used in DPDK. The configuration is kept the same to preserve the style. Sphinx generates the documentation from Python docstrings. The docstring format most suitable for DTS seems to be the Google format [0] which requires the sphinx.ext.napoleon extension. There are two requirements for building DTS docs: * The same Python version as DTS or higher, because Sphinx import the code. * Also the same Python packages as DTS, for the same reason. [0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings Signed-off-by: Juraj Linkeš --- doc/api/meson.build | 1 + doc/guides/conf.py | 22 ++++++++++++++---- doc/guides/meson.build | 1 + doc/guides/tools/dts.rst | 29 +++++++++++++++++++++++ dts/doc/doc-index.rst | 20 ++++++++++++++++ dts/doc/meson.build | 50 ++++++++++++++++++++++++++++++++++++++++ dts/meson.build | 16 +++++++++++++ meson.build | 1 + meson_options.txt | 2 ++ 9 files changed, 137 insertions(+), 5 deletions(-) create mode 100644 dts/doc/doc-index.rst create mode 100644 dts/doc/meson.build create mode 100644 dts/meson.build diff --git a/doc/api/meson.build b/doc/api/meson.build index 2876a78a7e..1f0c725a94 100644 --- a/doc/api/meson.build +++ b/doc/api/meson.build @@ -1,6 +1,7 @@ # SPDX-License-Identifier: BSD-3-Clause # Copyright(c) 2018 Luca Boccassi +doc_api_build_dir = meson.current_build_dir() doxygen = find_program('doxygen', required: get_option('enable_docs')) if not doxygen.found() diff --git a/doc/guides/conf.py b/doc/guides/conf.py index a55ce38800..04c842b67a 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -7,10 +7,9 @@ from sphinx import __version__ as sphinx_version from os import listdir from os import environ -from os.path import basename -from os.path import dirname +from os.path import basename, dirname from os.path import join as path_join -from sys import argv, stderr +from sys import argv, stderr, path import configparser @@ -24,6 +23,19 @@ file=stderr) pass +extensions = ['sphinx.ext.napoleon'] + +# Python docstring options +autodoc_member_order = 'bysource' +autodoc_typehints = 'both' +autodoc_typehints_format = 'short' +napoleon_numpy_docstring = False +napoleon_attr_annotations = True +napoleon_use_ivar = True +napoleon_use_rtype = False +add_module_names = False +toc_object_entries_show_parents = 'hide' + stop_on_error = ('-W' in argv) project = 'Data Plane Development Kit' @@ -35,8 +47,8 @@ html_show_copyright = False highlight_language = 'none' -release = environ.setdefault('DPDK_VERSION', "None") -version = release +path.append(environ.setdefault('DTS_ROOT', '.')) +version = environ.setdefault('DPDK_VERSION', "None") master_doc = 'index' diff --git a/doc/guides/meson.build b/doc/guides/meson.build index 51f81da2e3..8933d75f6b 100644 --- a/doc/guides/meson.build +++ b/doc/guides/meson.build @@ -1,6 +1,7 @@ # SPDX-License-Identifier: BSD-3-Clause # Copyright(c) 2018 Intel Corporation +doc_guides_source_dir = meson.current_source_dir() sphinx = find_program('sphinx-build', required: get_option('enable_docs')) if not sphinx.found() diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst index ebd6dceb6a..a547da2017 100644 --- a/doc/guides/tools/dts.rst +++ b/doc/guides/tools/dts.rst @@ -282,3 +282,32 @@ There are three tools used in DTS to help with code checking, style and formatti These three tools are all used in ``devtools/dts-check-format.sh``, the DTS code check and format script. Refer to the script for usage: ``devtools/dts-check-format.sh -h``. + + +Building DTS API docs +--------------------- + +To build DTS API docs, install the dependencies with Poetry, then enter its shell: + + .. code-block:: console + + poetry install --with docs + poetry shell + + +Build commands +~~~~~~~~~~~~~~ + +The documentation is built using the standard DPDK build system. + +After entering Poetry's shell, build the documentation with: + + .. code-block:: console + + ninja -C build dts/doc + +The output is generated in ``build/doc/api/dts/html``. + +.. Note:: + + Make sure to fix any Sphinx warnings when adding or updating docstrings. diff --git a/dts/doc/doc-index.rst b/dts/doc/doc-index.rst new file mode 100644 index 0000000000..10151c6851 --- /dev/null +++ b/dts/doc/doc-index.rst @@ -0,0 +1,20 @@ +.. DPDK Test Suite documentation master file, created by + sphinx-quickstart on Tue Mar 14 12:23:52 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to DPDK Test Suite's documentation! +=========================================== + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + modules + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/dts/doc/meson.build b/dts/doc/meson.build new file mode 100644 index 0000000000..db2bb0bed9 --- /dev/null +++ b/dts/doc/meson.build @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2023 PANTHEON.tech s.r.o. + +sphinx = find_program('sphinx-build', required: get_option('enable_dts_docs')) +sphinx_apidoc = find_program('sphinx-apidoc', required: get_option('enable_dts_docs')) + +if sphinx.found() and sphinx_apidoc.found() +endif + +dts_api_framework_dir = join_paths(dts_dir, 'framework') +dts_api_build_dir = join_paths(doc_api_build_dir, 'dts') +dts_api_src = custom_target('dts_api_src', + output: 'modules.rst', + command: ['SPHINX_APIDOC_OPTIONS=members,show-inheritance', + sphinx_apidoc, '--append-syspath', '--force', + '--module-first', '--separate', + '--doc-project', 'DTS', '-V', meson.project_version(), + '-o', dts_api_build_dir, + dts_api_framework_dir], + build_by_default: get_option('enable_dts_docs')) +doc_targets += dts_api_src +doc_target_names += 'DTS_API_sphinx_sources' + +cp = find_program('cp', required: get_option('enable_docs')) +cp_index = custom_target('cp_index', + input: 'doc-index.rst', + output: 'index.rst', + depends: dts_api_src, + command: [cp, '@INPUT@', join_paths(dts_api_build_dir, 'index.rst')], + build_by_default: get_option('enable_dts_docs')) +doc_targets += cp_index +doc_target_names += 'DTS_API_sphinx_index' + +extra_sphinx_args = ['-a', '-c', doc_guides_source_dir] +if get_option('werror') + extra_sphinx_args += '-W' +endif + +htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk') +dts_api_html = custom_target('dts_api_html', + output: 'html', + depends: cp_index, + command: ['DTS_ROOT=@0@'.format(dts_dir), + sphinx_wrapper, sphinx, meson.project_version(), + dts_api_build_dir, dts_api_build_dir, extra_sphinx_args], + build_by_default: get_option('enable_dts_docs'), + install: get_option('enable_dts_docs'), + install_dir: htmldir) +doc_targets += dts_api_html +doc_target_names += 'DTS_API_HTML' diff --git a/dts/meson.build b/dts/meson.build new file mode 100644 index 0000000000..17bda07636 --- /dev/null +++ b/dts/meson.build @@ -0,0 +1,16 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2023 PANTHEON.tech s.r.o. + +doc_targets = [] +doc_target_names = [] +dts_dir = meson.current_source_dir() + +subdir('doc') + +if doc_targets.length() == 0 + message = 'No docs targets found' +else + message = 'Built docs:' +endif +run_target('dts/doc', command: [echo, message, doc_target_names], + depends: doc_targets) diff --git a/meson.build b/meson.build index f91d652bc5..7820f334bb 100644 --- a/meson.build +++ b/meson.build @@ -84,6 +84,7 @@ subdir('app') # build docs subdir('doc') +subdir('dts') # build any examples explicitly requested - useful for developers - and # install any example code into the appropriate install path diff --git a/meson_options.txt b/meson_options.txt index 82c8297065..267f1b3ef7 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -16,6 +16,8 @@ option('drivers_install_subdir', type: 'string', value: 'dpdk/pmds-', d 'Subdirectory of libdir where to install PMDs. Defaults to using a versioned subdirectory.') option('enable_docs', type: 'boolean', value: false, description: 'build documentation') +option('enable_dts_docs', type: 'boolean', value: false, description: + 'Build DTS API documentation.') option('enable_apps', type: 'string', value: '', description: 'Comma-separated list of apps to build. If unspecified, build all apps.') option('enable_drivers', type: 'string', value: '', description: -- 2.30.2