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 544C94575D; Wed, 7 Aug 2024 14:04:02 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 8751140667; Wed, 7 Aug 2024 14:04:00 +0200 (CEST) Received: from mail-ej1-f41.google.com (mail-ej1-f41.google.com [209.85.218.41]) by mails.dpdk.org (Postfix) with ESMTP id A187F40608 for ; Wed, 7 Aug 2024 14:03:58 +0200 (CEST) Received: by mail-ej1-f41.google.com with SMTP id a640c23a62f3a-a7a9cf7d3f3so217482066b.1 for ; Wed, 07 Aug 2024 05:03:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1723032238; x=1723637038; darn=dpdk.org; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:user-agent:mime-version:date:message-id :from:to:cc:subject:date:message-id:reply-to; bh=Srs25xPYjvbqYpo8X3N1Qt2Qx+l8KaRoQbYJTEocp7w=; b=df0kP51E/E4ywd2LemltdN/ffnI1oDxPyrT27FLFWGF0WRnamexHKwGAhd13B9nqde 19BFh4oNG6ZClx2yT4P9JucDVRTzFzxaeZWZfaUWwevFxEw2OlxNuXfwos5rNDlQfa8k hBWezrbKEY3YGUjDEOafQqFzYBaVnyPmUtCbzDTdNQxDy9nhkjqTGS/CCAwduJiK1F4w 6nONjKAvWz0DjN8AWhr51hvtXAjUjgvbQ+f7tZ6IatNcwrpnFGlvDUh/2ReeLAl8lq0m W8aBcAHjGzJMtcsHqT+TVQkLRiXBfKuKCh9cDoJOs7hjH8Cx7gNmY4I2rPsa/0VPtvdB cyQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723032238; x=1723637038; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=Srs25xPYjvbqYpo8X3N1Qt2Qx+l8KaRoQbYJTEocp7w=; b=Ce+2MO2mMF2K2lYY/+25mMJJvLu5x9Gobdrc/b7C81RtVPwBCfe+0o96tPO4nPl+Ki IXAeQSPwF2YZhOPSaAG0JLRvrKk2YJNI/Aq9GVackxqaWrYr87xtZiGti7IoHhnCotmQ J4HGQ00ZEMn3t/Q/NsqbD5k0/yOqaKRa94QITGqXZEnLkpPJBwzPMD/JNCU0WBD4vhrx qwjCYgYi1BdFTIQt7tUENVqHboT6UnRuZ4l6HBhW4deEhELANn1Mx56Br0SBAg4Kr1js EL4QzR2DMG/oSJ2TqX11DjKb5dMKD7wFgInMvIrkawrgMuUZrdYRVLADAbWKbxEUKtXz p5+w== X-Forwarded-Encrypted: i=1; AJvYcCXQfLXGBfZg2GLQuoRoMkPAyTYK4udBPElKJvLpNsLANwWoIvCEQh0QSdOKdtGySXQefw5ScZsBJnYSH2o= X-Gm-Message-State: AOJu0YwcOI9LgHDvr4i+IUYdJ2eFIul3R6p5xT2AAfc4CFouhmIdaIwi zT4ma7eFmyBxBy6LP6NlInzWiE+7BAyZWjI77Yt7rZp6UCRKqdDA0VuGCqLqnRQ= X-Google-Smtp-Source: AGHT+IGCiQCRuWkeJT2xgmYUlwzE1v+D+mat6h5nlhp1zUttiZZlyrYidOTGoDGeUSHacOvC+gU5bQ== X-Received: by 2002:a17:906:7956:b0:a7d:48e3:4117 with SMTP id a640c23a62f3a-a7dc518febbmr1374092866b.68.1723032238106; Wed, 07 Aug 2024 05:03:58 -0700 (PDT) Received: from [192.168.200.22] ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a7dc9d437c6sm632660866b.129.2024.08.07.05.03.56 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 07 Aug 2024 05:03:57 -0700 (PDT) Message-ID: <9dfa8755-520b-42af-890c-30a3ff74f3a1@pantheon.tech> Date: Wed, 7 Aug 2024 14:03:55 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v15 5/5] dts: add API doc generation To: Thomas Monjalon Cc: 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, dev@dpdk.org References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240806151937.391917-1-juraj.linkes@pantheon.tech> <20240806151937.391917-6-juraj.linkes@pantheon.tech> <2156393.OBFZWjSADL@thomas> Content-Language: en-US From: =?UTF-8?Q?Juraj_Linke=C5=A1?= In-Reply-To: <2156393.OBFZWjSADL@thomas> Content-Type: text/plain; charset=UTF-8; format=flowed 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 On 7. 8. 2024 12:41, Thomas Monjalon wrote: > 06/08/2024 17:19, Juraj Linkeš: >> +"""Utilities for DTS dependencies. >> + >> +The module can be used as an executable script, >> +which verifies that the running Python version meets the version requirement of DTS. >> +The script returns the standard exit codes in this mode (0 is success, 1 is failure). > > Is it returning the list of dependencies for generating doc? > It's not worded right. When run as a script, it exits with the standard exit codes, it doesn't return anything. The function below is for returning the list of depedencies. >> + >> +The module also contains a function, get_missing_imports, >> +which looks for runtime and doc generation dependencies in the DTS pyproject.toml file >> +a returns a list of module names used in an import statement that are missing. > > typo? a -> and Ack. > > [...] >> +get_dts_deps = py3 + files('get-dts-deps.py') > > deps for runtime or doc? > may be good to specify in the name > It's getting both, actually. Now that I think about it, we don't need to get the docs dependencies, as we check for Sphinx elsewhere. We really only need to get the runtime dependencies and mock what's missing (that is add those to the autodoc_mock_imports config option). I think it makes sense to change the script and rename it to get-dts-runtime-deps.py (and the variable). > >> --- /dev/null >> +++ b/doc/api/dts/custom.css >> @@ -0,0 +1 @@ >> +../../guides/custom.css >> \ No newline at end of file > > Is it a link? Why? > call-sphinx-build.py copies the custom.css file. I added a link to preserve the look. >> +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(), meson.current_build_dir(), extra_sphinx_args], >> + build_by_default: get_option('enable_docs'), >> + install: get_option('enable_docs'), >> + install_dir: htmldir) > > When custom.css is copied? > I'm not sure what you're asking here. The call-sphinx-build.py copies it during the build and it's also copied during the install phase. > > >> +# 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'] > > What happens if napoleon and intersphinx are not available > when building basic DPDK doc without DTS? > > napoleon was added in version 1.3 and intersphinx in 0.5, so I didn't think of testing that. I tried adding a non-existent extension to the list and got this error: Extension error: Could not import extension sphinx.ext.foo (exception: No module named 'sphinx.ext.foo') I could add version checks for each of the extensions.