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 E283242C3E; Tue, 6 Jun 2023 12:49:55 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7A75940697; Tue, 6 Jun 2023 12:49:55 +0200 (CEST) Received: from mail-vs1-f47.google.com (mail-vs1-f47.google.com [209.85.217.47]) by mails.dpdk.org (Postfix) with ESMTP id 293FD40223 for ; Tue, 6 Jun 2023 12:49:54 +0200 (CEST) Received: by mail-vs1-f47.google.com with SMTP id ada2fe7eead31-43b2c7d9b52so1264167137.3 for ; Tue, 06 Jun 2023 03:49:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1686048593; x=1688640593; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=wB10gssNZTBK27ZEwvk6qcYLmVhmm1S1CS/QQQoKFHI=; b=l+0srT3mCVLGWytuyE59zyQTgk65uHwm6yI9S2U40fkkIOkmNdTkbp7tznR1hv3NA0 VymD22SVlswUIDa0SIWpbbJ31Wh5NBIWk1v3qoW91HLFuYaRhda/RFc+mSyrKsUqWIqg FH8gf7KkYgs1gqDEs6VqNl8FzeZg13ZYTbyg5/b0/dUhM2Yh7RP2U21OBgZu5iegRLky 9g4lkrzntA9AiHRHVei6se170qIEM74/8VRC4W+cWZwXTNYCjXij69TvOzgpec+xabAo 0TVZDIAuaC2UXZGBSXMhjI86cIGAOASG0mzrhNeRYPDlCbCrqwP+gBlqlVySmtDDt0e6 pwPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1686048593; x=1688640593; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=wB10gssNZTBK27ZEwvk6qcYLmVhmm1S1CS/QQQoKFHI=; b=L2qYhPYvXl6c2kFT0V9dbOi6fqyYpWZsqU1Uo2LnpBNmB7XUdy6rYct8ma699hXsvJ THVKigsii28Dieml7qpLsVx5Tvc7Ov0ie7J2g499oNx96Km8T5YZsynuV/ptm01Q/Djr r2637UD0renlYiI+2t1JOurfNBWlIZUHTRLFeHG5s3Ym/fd72Bh8Hz4fkozkGSEdQnFx OjwHoH2FvAf9G3jUAQSZpU/ddzQhxHRIS2RGGhnElS66E/R/v/49S0F96tzle7M9JDEt WY2+eg5e1IMGjLUbr/NmVBmqE0YITd+fu2RtHNK01wxgRN1Yeq1vN2KFw2P2tQt9rGb3 EmkQ== X-Gm-Message-State: AC+VfDwknBAs8djdb15YumXRVGYYJDRNaBVlmFzmCgHEZHmI/ERVDWVx DFn34Pfy4rNmaXywEKGqJk9a9HwBJV01r0PlqbQ= X-Google-Smtp-Source: ACHHUZ4OXMBjmhQtjegeM+7GOG01U44zVpHSkK1muo1WhhR5Wln9ewp9euexNdkTKszoJyAtvJ/v8jb4CAwSr1UOrOw= X-Received: by 2002:a67:be0c:0:b0:43b:5823:6664 with SMTP id x12-20020a67be0c000000b0043b58236664mr912665vsq.3.1686048593282; Tue, 06 Jun 2023 03:49:53 -0700 (PDT) MIME-Version: 1.0 References: <20230601153801.118616-1-bruce.richardson@intel.com> In-Reply-To: From: Jerin Jacob Date: Tue, 6 Jun 2023 16:19:27 +0530 Message-ID: Subject: Re: [PATCH] doc: build manpages as well as html output To: Bruce Richardson Cc: dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 Tue, Jun 6, 2023 at 3:49=E2=80=AFPM Bruce Richardson wrote: > > On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote: > > On Tue, Jun 6, 2023 at 2:49=E2=80=AFPM Bruce Richardson > > wrote: > > > > > > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote: > > > > On Thu, Jun 1, 2023 at 9:08=E2=80=AFPM Bruce Richardson > > > > wrote: > > > > > > > > > > Doxygen can produce manpage output as well as html output for the= DPDK > > > > > APIs. However, we need to do this as a separate task as the manpa= ge > > > > > output needs to be placed in a different location post-install to= the > > > > > html output (/usr/local/share/man vs /usr/local/share/doc/). > > > > > > > > > > Changes required are: > > > > > * Add configurable options for manpage output and html output to = the > > > > > doxygen config template. (Remove option for html output path as= it's > > > > > always "html") > > > > > * Modify API meson.build file to configure two separate doxygen c= onfig > > > > > files, for HTML and manpages respectively. > > > > > * Change doxygen wrapper script to have separate output log files= for > > > > > the manpage and HTML jobs, to avoid conflicts > > > > > * Add "custom_targets" to meson.build file to build the HTML page= s and > > > > > the manpages, with individual install locations for each. > > > > > * Where supported by meson version, call "mandb" post-install to = update > > > > > the man database to ensure the new manpages can be found. > > > > > > > > > > Signed-off-by: Bruce Richardson > > > > > > > > > + > > > > > +mandb =3D find_program('mandb', required: false) > > > > > +if mandb.found() and get_option('enable_docs') and meson.version= ().version_compare('>=3D0.55.0') > > > > > + meson.add_install_script(mandb) > > > > > > > > It does not look like just executing mandb it is adding these man > > > > pages to database > > > > > > > > log: > > > > Running custom install script '/usr/bin/mandb' > > > > Purging old database entries in /home/jerin/.local/man... > > > > Processing manual pages under /home/jerin/.local/man... > > > > Checking for stray cats under /home/jerin/.local/man... > > > > Processing manual pages under /home/jerin/.local/man/cat1... > > > > Purging old database entries in /home/jerin/.local/share/man... > > > > Processing manual pages under /home/jerin/.local/share/man... > > > > Checking for stray cats under /home/jerin/.local/share/man... > > > > Processing manual pages under /home/jerin/.local/share/man/cat1... > > > > 0 man subdirectories contained newer manual pages. > > > > 0 manual pages were added. > > > > 0 stray cats were added. > > > > 0 old database entries were purged. > > > > > > > > [main][dpdk.org] $ man rte_flow_create > > > > No manual entry for rte_flow_create > > > > > > > > # Following works by providing the path i.e man pages created prope= rly > > > > only db update is missing > > > > man --manpath=3D/tmp/i/usr/local/share/man/ rte_flow_create > > > > > > > Yes, that is correct. > > > > > > If you install to a non-standard location, then yes you need to updat= e > > > manpath yourself. However, in case you install to a "standard" locati= on, > > > then running mandb will update the database for you. I believe this i= s the > > > behaviour we should have. I view it as the same as installing binarie= s in a > > > standard vs non-standard path - if the binaries are placed in a stand= ard > > > location then they are found automatically, but if installed in a cus= tom > > > location, then the user is responsible for ensuring all paths are cor= rect. > > > > OK. Then I think, we can move "meson.add_install_script(mandb)" > > invocation under !DESTDIR not provided. > > As if DESTDIR is provided then there is no use for mandb. > > > That would mean adding a new build script to run mandb, since: > * meson doesn't directly support getting environment variables > * DESTDIR may only be set at install time rather than at configuration > time, so we'll always need to set up the build script > > Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary > runs of mandb, since using a special "prefix" setting would also cause th= e > manpages to not be found. > > Overall, I'd view the complexity of avoiding the mandb call not to be > worth it, since calling mandb is largely harmless - bar the time taken to > run it. However, if you feel strongly it should be skipped when installin= g > with DESTDIR No strong option. OK to skip DESTDIR check. >, I'll spin a v2 with the wrapper script added. Let me know > what you think? I think, it is good to update doc/guides/contributing/documentation.rst on how to use the man page(i.e use with --manpage) > > /Bruce