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 00F6841FDB; Thu, 31 Aug 2023 12:04:39 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id AF8F4402A9; Thu, 31 Aug 2023 12:04:17 +0200 (CEST) Received: from mail-ej1-f48.google.com (mail-ej1-f48.google.com [209.85.218.48]) by mails.dpdk.org (Postfix) with ESMTP id 76C644029A for ; Thu, 31 Aug 2023 12:04:14 +0200 (CEST) Received: by mail-ej1-f48.google.com with SMTP id a640c23a62f3a-9a5e37a39ecso63322466b.3 for ; Thu, 31 Aug 2023 03:04:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1693476254; x=1694081054; 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=t5AXyyfurcLC25SwdG8h94cYwrGu3ryYjLX2lA5npiM=; b=cJ2NLrlaXWPNyD16F1ORqtSPOKDjpAu9UQVaasfGaJmkiiRNC4rqBmwdozrw7bT1ve BrmKoZeRZIQejo8uLq1hN8xSJfvBxV+6A3UgmmTGw/n5SoYzHj3OfqrunztNJ+57XdDK waTCtJPR/HQbZechYvE3XBWvTjSQ3fkYDAPv40T+sRHfwuGkroqItAFEvJ0aW92D77th r7/SV1wQ6rMeOGIeYFCSOAwewG9yHoaT6XPC0OhTRVnU717u675qqx8PkUjzhI9sgct0 AkWX4JqeYN7ycJc2tcBcOU7iqSi6hRHxa1PerEtKh4MfffGoeOvO1dQws+nK1ShVgK5Y nCYQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693476254; x=1694081054; 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=t5AXyyfurcLC25SwdG8h94cYwrGu3ryYjLX2lA5npiM=; b=DsEHXIrbQ7/y7cpJsecZt6k8JVwrWE5qci0w7qhG18RwEH3EEZlGd8AZjk6KemO07a S2OpCB+4sW1da+2W+ENFG0B4hrsvotvzMtHiVgCOZjUdS52SSgKE2u0A6KtCCPd9XndF e2RlD/zHJBtKzOIQVlrJoS+e3qICemuqEnewxSnzHQcyTJ95jBRspz+JJAMUjMmTpZxQ SqLdCHBoKACN9eddwdZctMiQew+6M9ylfVN7Siqn3ukABOFmaXd4zqs+ZVHeeQTtVLJa Zb0Z3CEBDlLevYFAxqd6R+crCK1RvZPYvl/ElbzeaxyslFoGOO+FFouOSQYYqbw9Rq3p rUlQ== X-Gm-Message-State: AOJu0YwpE/Fjy+C+yPoQXYGRkY0ElMKsaCbmj23CNcL4FfOme3WPy+kh H41UJvGbWddpND5l7htmflFUJg== X-Google-Smtp-Source: AGHT+IFsXHi25fULqZd8GsERJuZ9Ye/crRqlpqV10jNhYE6uM2uFl1HKpWB4Jg/3BA+VwdmbiygzPg== X-Received: by 2002:a17:906:1daa:b0:9a1:6bc1:b518 with SMTP id u10-20020a1709061daa00b009a16bc1b518mr3094127ejh.29.1693476254094; Thu, 31 Aug 2023 03:04:14 -0700 (PDT) Received: from jlinkes-PT-Latitude-5530.. (ip-46.34.238.3.o2inet.sk. [46.34.238.3]) by smtp.gmail.com with ESMTPSA id l18-20020a1709066b9200b0099bc08862b6sm587513ejr.171.2023.08.31.03.04.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Aug 2023 03:04:13 -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, jspewock@iol.unh.edu, probb@iol.unh.edu Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= Subject: [RFC PATCH v4 3/4] dts: add doc generation Date: Thu, 31 Aug 2023 12:04:06 +0200 Message-Id: <20230831100407.59865-4-juraj.linkes@pantheon.tech> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230831100407.59865-1-juraj.linkes@pantheon.tech> References: <20230511091408.236638-1-juraj.linkes@pantheon.tech> <20230831100407.59865-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š --- buildtools/call-sphinx-build.py | 29 ++++++++++++------- doc/api/meson.build | 1 + doc/guides/conf.py | 32 +++++++++++++++++---- doc/guides/meson.build | 1 + doc/guides/tools/dts.rst | 29 +++++++++++++++++++ dts/doc/doc-index.rst | 17 +++++++++++ dts/doc/meson.build | 50 +++++++++++++++++++++++++++++++++ dts/meson.build | 16 +++++++++++ meson.build | 1 + 9 files changed, 161 insertions(+), 15 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/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py index 39a60d09fa..c2f3acfb1d 100755 --- a/buildtools/call-sphinx-build.py +++ b/buildtools/call-sphinx-build.py @@ -3,37 +3,46 @@ # Copyright(c) 2019 Intel Corporation # +import argparse import sys import os from os.path import join from subprocess import run, PIPE, STDOUT from packaging.version import Version -# assign parameters to variables -(sphinx, version, src, dst, *extra_args) = sys.argv[1:] +parser = argparse.ArgumentParser() +parser.add_argument('sphinx') +parser.add_argument('version') +parser.add_argument('src') +parser.add_argument('dst') +parser.add_argument('--dts-root', default='.') +args, extra_args = parser.parse_known_args() # set the version in environment for sphinx to pick up -os.environ['DPDK_VERSION'] = version +os.environ['DPDK_VERSION'] = args.version +os.environ['DTS_ROOT'] = args.dts_root # for sphinx version >= 1.7 add parallelism using "-j auto" -ver = run([sphinx, '--version'], stdout=PIPE, +ver = run([args.sphinx, '--version'], stdout=PIPE, stderr=STDOUT).stdout.decode().split()[-1] -sphinx_cmd = [sphinx] + extra_args +sphinx_cmd = [args.sphinx] + extra_args if Version(ver) >= Version('1.7'): sphinx_cmd += ['-j', 'auto'] # find all the files sphinx will process so we can write them as dependencies srcfiles = [] -for root, dirs, files in os.walk(src): +for root, dirs, files in os.walk(args.src): srcfiles.extend([join(root, f) for f in files]) # run sphinx, putting the html output in a "html" directory -with open(join(dst, 'sphinx_html.out'), 'w') as out: - process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')], - stdout=out) +with open(join(args.dst, 'sphinx_html.out'), 'w') as out: + process = run( + sphinx_cmd + ['-b', 'html', args.src, join(args.dst, 'html')], + stdout=out + ) # create a gcc format .d file giving all the dependencies of this doc build -with open(join(dst, '.html.d'), 'w') as d: +with open(join(args.dst, '.html.d'), 'w') as d: d.write('html: ' + ' '.join(srcfiles) + '\n') sys.exit(process.returncode) 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 0f7ff5282d..737e5a5688 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,29 @@ file=stderr) pass +extensions = ['sphinx.ext.napoleon'] + +# Python docstring options +autodoc_default_options = { + 'members': True, + 'member-order': 'bysource', + 'show-inheritance': True, +} +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 = False + +# Sidebar config +html_theme_options = { + 'collapse_navigation': False, + 'navigation_depth': -1, +} + stop_on_error = ('-W' in argv) project = 'Data Plane Development Kit' @@ -35,8 +57,8 @@ html_show_copyright = False highlight_language = 'none' -release = environ.setdefault('DPDK_VERSION', "None") -version = release +path.append(environ.get('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 32c18ee472..98923b1467 100644 --- a/doc/guides/tools/dts.rst +++ b/doc/guides/tools/dts.rst @@ -335,3 +335,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..f5dcd553f2 --- /dev/null +++ b/dts/doc/doc-index.rst @@ -0,0 +1,17 @@ +.. DPDK Test Suite documentation. + +Welcome to DPDK Test Suite's documentation! +=========================================== + +.. toctree:: + :titlesonly: + :caption: Contents: + + framework + +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..8e70eabc51 --- /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') +sphinx_apidoc = find_program('sphinx-apidoc') + +if not sphinx.found() or not sphinx_apidoc.found() + subdir_done() +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, '--append-syspath', '--force', + '--module-first', '--separate', '-V', meson.project_version(), + '-o', dts_api_build_dir, '--no-toc', '--implicit-namespaces', + dts_api_framework_dir], + build_by_default: false) +doc_targets += dts_api_src +doc_target_names += 'DTS_API_sphinx_sources' + +cp = find_program('cp') +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: false) +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, + '--dts-root', dts_dir, extra_sphinx_args], + build_by_default: false, + install: false, + 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 39cb73846d..4d34dc531c 100644 --- a/meson.build +++ b/meson.build @@ -85,6 +85,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 -- 2.34.1