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 985734570F; Thu, 1 Aug 2024 11:38:21 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 35B1D402C8; Thu, 1 Aug 2024 11:37:52 +0200 (CEST) Received: from mail-ej1-f47.google.com (mail-ej1-f47.google.com [209.85.218.47]) by mails.dpdk.org (Postfix) with ESMTP id 8B6674336D for ; Thu, 1 Aug 2024 11:37:49 +0200 (CEST) Received: by mail-ej1-f47.google.com with SMTP id a640c23a62f3a-a7a83a968ddso948748566b.0 for ; Thu, 01 Aug 2024 02:37:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722505069; x=1723109869; 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=im7l4zn+lBPS5yqcf+F/QHh4bRh4V4A8hC9IOSUjmN4=; b=g6sUyK+YqIxxErR+HqoBcGwm9UZtwwgoY1ATh59AiNVMT/5QJ/dzPyey8rzb1dbY0V Ca+s2lFZQFQFuxel/YEzNrqmJf+F1o7c5fZgm2j4WANPPLsWS+BdoOGRhWAXfe1UBzYo 5n573vcgAMEXH3mmYzIOZIqSKz9jJurKPsbcJoWNCMzD1BP0rtSWF6N3PHO6NmLgT+4K bBuxrnGzs/lOlsE8G+JCvobA3/HpvChg9yUGA2QXUyMjjXDhv+urF2vxlktUdL7y6f/b PBVxQwjleQ+NSGATkYTFxdbdCRYBLb1zlZdE/bnBn+lGGvZv355UNYpqFY2m32QMeMrp fKOA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722505069; x=1723109869; 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=im7l4zn+lBPS5yqcf+F/QHh4bRh4V4A8hC9IOSUjmN4=; b=Ne/fjigLNVHR4Y3X8Mryb/ZteJ9DQ0AkbaLJA1hScp2SVHiO/4CB5h+JKIebJ0CwFH 1L8PtewvRvEOuXxewE/k561hrHmWj2RVY6FOXJfX7E5277NHtDFaMTs0MZsUcBUqEmvF z0+hz3QB5gzfAB11J5pPwMM12cFslDYMrnky44bNYfzxGlo3yfGQWbRz8AP+auMWr95p rq3GXttL8OOlrSGfxvhzflgFysOjTL4D+xeAnitzwVftQd4TxYHLwugWIx9cLj7kKAJb 9+sXe+VSBu2VyaKrFZsuAUov5rppwV6fbA8NuxtAaulKm2IHTmnX+h6hbjynFIGEn2bx 9FWw== X-Gm-Message-State: AOJu0YxWs6th/1gWW/nrC5h2CNDN8C1j0oErWeo5YwLJZc0ROYtxyGyp m7wP18U8F+uCq49KQIcFDdPzbJIhRsJaA07pNqAWC3Uq6odoHyK+b9pCAIDcEDM= X-Google-Smtp-Source: AGHT+IEmtf7XytGsFiq2TIXd8+l4LE6tEYw6Zo7syM/IZRPKskf0P+2r6UUxocqaCSiX7eJ8aStskw== X-Received: by 2002:a17:907:c1f:b0:a7a:bd5a:1eb7 with SMTP id a640c23a62f3a-a7daf76a1e7mr155977166b.59.1722505068996; Thu, 01 Aug 2024 02:37:48 -0700 (PDT) Received: from localhost.localdomain ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a7acab236eesm869742266b.22.2024.08.01.02.37.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Aug 2024 02:37:48 -0700 (PDT) From: =?UTF-8?q?Juraj=20Linke=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, Luca.Vizzarro@arm.com, npratte@iol.unh.edu Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= , Luca Vizzarro Subject: [PATCH v10 5/5] dts: add API doc generation Date: Thu, 1 Aug 2024 11:37:40 +0200 Message-Id: <20240801093740.237929-6-juraj.linkes@pantheon.tech> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240801093740.237929-1-juraj.linkes@pantheon.tech> References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240801093740.237929-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 DTS API docs is Sphinx, which is already in use in DPDK. The same configuration is used to preserve style with one DTS-specific configuration (so that the DPDK docs are unchanged) that modifies how the sidebar displays the content. Sphinx generates the documentation from Python docstrings. The docstring format is the Google format [0] which requires the sphinx.ext.napoleon extension. The other extension, sphinx.ext.intersphinx, enables linking to objects in external documentations, such as the Python documentation. There are two requirements for building DTS docs: * The same Python version as DTS or higher, because Sphinx imports 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š Reviewed-by: Luca Vizzarro Reviewed-by: Jeremy Spewock Acked-by: Bruce Richardson Tested-by: Luca Vizzarro Tested-by: Nicholas Pratte --- buildtools/call-sphinx-build.py | 5 ++++- doc/api/doxy-api-index.md | 3 +++ doc/api/doxy-api.conf.in | 2 ++ doc/api/meson.build | 4 ++++ doc/guides/conf.py | 33 +++++++++++++++++++++++++++++++- doc/guides/meson.build | 1 + doc/guides/tools/dts.rst | 34 ++++++++++++++++++++++++++++++++- dts/doc/meson.build | 27 ++++++++++++++++++++++++++ dts/meson.build | 16 ++++++++++++++++ meson.build | 1 + 10 files changed, 123 insertions(+), 3 deletions(-) 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 2034160049..c55d4f6bc9 100755 --- a/buildtools/call-sphinx-build.py +++ b/buildtools/call-sphinx-build.py @@ -16,10 +16,13 @@ parser.add_argument('version') parser.add_argument('src') parser.add_argument('dst') +parser.add_argument('--dts-root', default=None) args, extra_args = parser.parse_known_args() # set the version in environment for sphinx to pick up os.environ['DPDK_VERSION'] = args.version +if args.dts_root: + os.environ['DTS_ROOT'] = args.dts_root sphinx_cmd = [args.sphinx] + extra_args @@ -46,7 +49,7 @@ css = 'custom.css' src_css = join(args.src, css) dst_css = join(args.dst, 'html', '_static', 'css', css) -if not os.path.exists(dst_css) or not filecmp.cmp(src_css, dst_css): +if os.path.exists(src_css) and (not os.path.exists(dst_css) or not filecmp.cmp(src_css, dst_css)): os.makedirs(os.path.dirname(dst_css), exist_ok=True) shutil.copyfile(src_css, dst_css) diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index f9f0300126..ab223bcdf7 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -245,3 +245,6 @@ The public API headers are grouped by topics: [experimental APIs](@ref rte_compat.h), [ABI versioning](@ref rte_function_versioning.h), [version](@ref rte_version.h) + +- **tests**: + [**DTS**](@dts_api_main_page) diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index a8823c046f..c94f02d411 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -124,6 +124,8 @@ SEARCHENGINE = YES SORT_MEMBER_DOCS = NO SOURCE_BROWSER = YES +ALIASES = "dts_api_main_page=@DTS_API_MAIN_PAGE@" + EXAMPLE_PATH = @TOPDIR@/examples EXAMPLE_PATTERNS = *.c EXAMPLE_RECURSIVE = YES diff --git a/doc/api/meson.build b/doc/api/meson.build index b828b1ed66..ffc75d7b5a 100644 --- a/doc/api/meson.build +++ b/doc/api/meson.build @@ -41,6 +41,10 @@ cdata.set('WARN_AS_ERROR', 'NO') if get_option('werror') cdata.set('WARN_AS_ERROR', 'YES') endif +# A local reference must be relative to the main index.html page +# The path below can't be taken from the DTS meson file as that would +# require recursive subdir traversal (doc, dts, then doc again) +cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html')) # configure HTML Doxygen run html_cdata = configuration_data() diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 8b440fb2a9..b442a1f76c 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -9,7 +9,7 @@ from os import environ 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 @@ -23,6 +23,37 @@ file=stderr) pass +# Napoleon enables the Google format of Python doscstrings, used in DTS +# Intersphinx allows linking to external projects, such as Python docs, also used in DTS +extensions = ['sphinx.ext.napoleon', 'sphinx.ext.intersphinx'] + +# DTS Python docstring options +autodoc_default_options = { + 'members': True, + 'member-order': 'bysource', + 'show-inheritance': True, +} +autodoc_class_signature = 'separated' +autodoc_typehints = 'both' +autodoc_typehints_format = 'short' +autodoc_typehints_description_target = 'documented' +napoleon_numpy_docstring = False +napoleon_attr_annotations = True +napoleon_preprocess_types = True +add_module_names = False +toc_object_entries = True +toc_object_entries_show_parents = 'hide' +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +dts_root = environ.get('DTS_ROOT') +if dts_root: + path.append(dts_root) + # DTS Sidebar config + html_theme_options = { + 'collapse_navigation': False, + 'navigation_depth': -1, + } + stop_on_error = ('-W' in argv) project = 'Data Plane Development Kit' diff --git a/doc/guides/meson.build b/doc/guides/meson.build index f8bbfba9f5..b34b7b8eb0 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 515b15e4d8..77df7a0378 100644 --- a/doc/guides/tools/dts.rst +++ b/doc/guides/tools/dts.rst @@ -292,7 +292,12 @@ and try not to divert much from it. The :ref:`DTS developer tools ` will issue warnings when some of the basics are not met. -The code must be properly documented with docstrings. +The API documentation, which is a helpful reference when developing, may be accessed +in the code directly or generated with the :ref:`API docs build steps `. +When adding new files or modifying the directory structure, +the corresponding changes must be made to DTS api doc sources in ``dts/doc``. + +Speaking of which, the code must be properly documented with docstrings. The style must conform to the `Google style `_. See an example of the style `here @@ -427,6 +432,33 @@ the DTS code check and format script. Refer to the script for usage: ``devtools/dts-check-format.sh -h``. +.. _building_api_docs: + +Building DTS API docs +--------------------- + +To build DTS API docs, install the dependencies with Poetry, then enter its shell: + +.. code-block:: console + + poetry install --no-root --with docs + poetry shell + +The documentation is built using the standard DPDK build system. +After executing the meson command and 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, + and also run the ``devtools/dts-check-format.sh`` script and address any issues it finds. + + Configuration Schema -------------------- diff --git a/dts/doc/meson.build b/dts/doc/meson.build new file mode 100644 index 0000000000..01b7b51034 --- /dev/null +++ b/dts/doc/meson.build @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2023 PANTHEON.tech s.r.o. + +sphinx = find_program('sphinx-build', required: false) +sphinx_apidoc = find_program('sphinx-apidoc', required: false) + +if not sphinx.found() or not sphinx_apidoc.found() + subdir_done() +endif + +dts_doc_api_build_dir = join_paths(doc_api_build_dir, 'dts') + +extra_sphinx_args = ['-E', '-c', doc_guides_source_dir, '--dts-root', dts_dir] +if get_option('werror') + extra_sphinx_args += '-W' +endif + +htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk', 'dts') +dts_api_html = custom_target('dts_api_html', + output: 'html', + command: [sphinx_wrapper, sphinx, meson.project_version(), + meson.current_source_dir(), dts_doc_api_build_dir, extra_sphinx_args], + build_by_default: false, + install: get_option('enable_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..e8ce0f06ac --- /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 8b248d4505..835973a0ce 100644 --- a/meson.build +++ b/meson.build @@ -87,6 +87,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