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 760874575D; Wed, 7 Aug 2024 15:12:07 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F1E764028C; Wed, 7 Aug 2024 15:12:06 +0200 (CEST) Received: from mail-ed1-f52.google.com (mail-ed1-f52.google.com [209.85.208.52]) by mails.dpdk.org (Postfix) with ESMTP id BD4044027B for ; Wed, 7 Aug 2024 15:12:04 +0200 (CEST) Received: by mail-ed1-f52.google.com with SMTP id 4fb4d7f45d1cf-5b7b6a30454so2571220a12.2 for ; Wed, 07 Aug 2024 06:12:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1723036324; x=1723641124; 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=BPeFxn7jFMCbfvrR2Gf7vXKpSR7VKajawbEh4SRB/co=; b=A76rNYJBCmqmuw+MkAXjAN6RJVVLfTMSOEf9Yzy6A42g3a9ofk+IxZP5iDT4xdOkjW DDfT3URVDX4VW/ll8ny6Y9Fd3v2VorZLBTL9bsHu+OQSEiV0/87pIklUbv29W0fWfJii /vao3A79lfOMSQWoXOUCp/qomxF4HA4i7GIznYTwjaMIV7g89QFfXkVLAMClhVYuP19q UjNKNK2kQGACFmnIyZkmVjYR6moO/2OK6Tr8LVpEdX3d2EbmGQ3Bh9NK5yUbtItJ36/n 8Nj/n+rnTkjPK/ZW4cXXmMi4nXCmVbwD5t+5ateRZk0MF2yFHDILdY9EmOwM+fEtzVlR cVtQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723036324; x=1723641124; 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=BPeFxn7jFMCbfvrR2Gf7vXKpSR7VKajawbEh4SRB/co=; b=nzWfeN0iPvxIldrOr4iDqGV4J6O3nmG/ZcTu/fpk9ulQEAtfvSe+W33spJ9uQIdLlP o2TCiF/ua4cKjlKpMQXXV+Crhua/EsTf12BwhBSojDXPBqBsicKtCqM3sdD1m2MTj1qr Ev03PpQgfpkAnPpjiEW1rWiyrY8ODuhosFGubnJJEN+ou/DOj0nN0geFDrT1y5vI7AFM PMPkvm2sFZoaZUMc+ebNb5EEqwCG5BrHCOMDQRwKcWUqbEFr5DM6nAXZNusJ0H2p6DMx BV0i36qXG7TPR58kVWrGHnfqh9yKh4HAGNKj8xxoHvOxXujXSHtq5tMqp6Hq+p0Rg2Xq FGpw== X-Forwarded-Encrypted: i=1; AJvYcCW4IyFuw60c3IGf2r2T5wIIGYPEHfeD2PpShUUh1JBe3GjTMDtb006xXsIFf7Lt2DvLFilKTjXBlJoK8ow= X-Gm-Message-State: AOJu0YzOZfcGPG8pmiQazlqpF2IdRvEqrQ8Uz8CK2Ey65LSicfDNs4HY 6lG5JAhzJ6iQsX4WrZ6Fvl3ooM9sTv9HZYpJTYSj9Curnu16lKCp/7StU4YspHs= X-Google-Smtp-Source: AGHT+IHxsYDW1I2B+cSVcCROJqhMBSUKoYs+lBz0wnmUrstuYCxoZ9U8rODqZQHtAiAw/0ijtZkrSg== X-Received: by 2002:aa7:de82:0:b0:5a8:2f2b:d2c9 with SMTP id 4fb4d7f45d1cf-5b7f40a506fmr12053603a12.21.1723036324172; Wed, 07 Aug 2024 06:12:04 -0700 (PDT) Received: from [192.168.200.22] ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5b83b92cbccsm7009925a12.68.2024.08.07.06.12.03 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 07 Aug 2024 06:12:03 -0700 (PDT) Message-ID: <16e9f263-f6f9-4724-8111-cdd74f063ea7@pantheon.tech> Date: Wed, 7 Aug 2024 15:12:02 +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> <2156393.OBFZWjSADL@thomas> <9dfa8755-520b-42af-890c-30a3ff74f3a1@pantheon.tech> <14011012.RDIVbhacDa@thomas> Content-Language: en-US From: =?UTF-8?Q?Juraj_Linke=C5=A1?= In-Reply-To: <14011012.RDIVbhacDa@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 14:27, Thomas Monjalon wrote: > 07/08/2024 14:03, Juraj Linkeš: >> On 7. 8. 2024 12:41, Thomas Monjalon wrote: >>> 06/08/2024 17:19, Juraj Linkeš: >>> [...] >>>> +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). > > OK > >>>> --- /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. > > The file is copied in _static dir of sphinx guides. > How does it work for DTS API? > It works the same way. shutil.copyfile (which is used to copy the file) follows symlinks, so DTS API gets a copy in its _static dir (doc/api/dts/html/_static/css). I did it this way to preserve the style in case there's something in the css file that applies to both DPDK and DTS API docs. > >>>> +# 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. > > My concern is to allow generating DPDK doc without DTS, > without the new extra dependencies. > Ok, I think putting all of these into the DTS if branch ("if environ.get('DTS_BUILD'):") would make sense then.