From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id 2B0A21559 for ; Wed, 12 Sep 2018 11:36:06 +0200 (CEST) X-Amp-Result: UNSCANNABLE X-Amp-File-Uploaded: False Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 12 Sep 2018 02:36:06 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,364,1531810800"; d="scan'208";a="261911349" Received: from bricha3-mobl.ger.corp.intel.com ([10.237.221.107]) by fmsmga005.fm.intel.com with SMTP; 12 Sep 2018 02:36:00 -0700 Received: by (sSMTP sendmail emulation); Wed, 12 Sep 2018 10:36:00 +0100 Date: Wed, 12 Sep 2018 10:36:00 +0100 From: Bruce Richardson To: Luca Boccassi Cc: dev@dpdk.org Message-ID: <20180912093600.GB15632@bricha3-MOBL.ger.corp.intel.com> References: <20180911161322.20114-1-bruce.richardson@intel.com> <1536698168.10952.34.camel@debian.org> <1536702478.10952.36.camel@debian.org> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <1536702478.10952.36.camel@debian.org> Organization: Intel Research and Development Ireland Ltd. User-Agent: Mutt/1.10.1 (2018-07-13) Subject: Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Sep 2018 09:36:07 -0000 On Tue, Sep 11, 2018 at 10:47:58PM +0100, Luca Boccassi wrote: > On Tue, 2018-09-11 at 21:36 +0100, Luca Boccassi wrote: > > On Tue, 2018-09-11 at 17:13 +0100, Bruce Richardson wrote: > > > Signed-off-by: Bruce Richardson > > > --- > > > NOTE: this patch depends upon: > > > http://patches.dpdk.org/project/dpdk/list/?series=1232 > > > > Just a reminder that's v2, and the patch won't apply cleanly on the > > latest revision > > > > >  doc/api/meson.build    |  3 ++- > > >  doc/guides/meson.build | 16 ++++++++++++++++ > > >  doc/meson.build        | 11 +++++++++++ > > >  3 files changed, 29 insertions(+), 1 deletion(-) > > >  create mode 100644 doc/guides/meson.build > > > > > > diff --git a/doc/api/meson.build b/doc/api/meson.build > > > index 5dfa0fe04..f9bee4dac 100644 > > > --- a/doc/api/meson.build > > > +++ b/doc/api/meson.build > > > @@ -50,5 +50,6 @@ if doxygen.found() > > >   install_dir: htmldir, > > >   build_by_default: false) > > >   > > > - run_target('doc', command: 'true', depends: doxy_build) > > > + doc_targets += doxy_build > > > + doc_target_names += 'Doxygen_API' > > >  endif > > > diff --git a/doc/guides/meson.build b/doc/guides/meson.build > > > new file mode 100644 > > > index 000000000..6d1e2990d > > > --- /dev/null > > > +++ b/doc/guides/meson.build > > > @@ -0,0 +1,16 @@ > > > +# SPDX-License-Identifier: BSD-3-Clause > > > +# Copyright(c) 2017 Intel Corporation > > > > s/2017/2018 > > > > > +sphinx = find_program('sphinx-build', required: > > > get_option('enable_docs')) > > > + > > > +if sphinx.found() > > > + html_guides_build = custom_target('html_guides_build', > > > + input: meson.current_source_dir(), > > > + output: 'index.html', > > > > As we discussed I don't have a good solution, but right now running > > ninja will rebuild these sphinx docs again and again, which will be a > > bit annoying when using enable_docs=true as it will always happen. > > Changing output to 'html' fixes the issue and it makes it build only > > once, but then they won't rebuild if the docs change as you noted. > > > > > + command: [sphinx, '-b', 'html', '@INPUT@', > > > meson.current_build_dir() + '/html'], > > > + build_by_default: false, > > > + install: get_option('enable_docs')) > > > + > > > + doc_targets += html_guides_build > > > + doc_target_names += 'HTML_Guides' > > > +endif > > > diff --git a/doc/meson.build b/doc/meson.build > > > index afca2e713..c5410d85d 100644 > > > --- a/doc/meson.build > > > +++ b/doc/meson.build > > > @@ -1,4 +1,15 @@ > > >  # SPDX-License-Identifier: BSD-3-Clause > > >  # Copyright(c) 2018 Luca Boccassi > > >   > > > +doc_targets = [] > > > +doc_target_names = [] > > >  subdir('api') > > > +subdir('guides') > > > + > > > +if doc_targets.length() == 0 > > > + message = 'No docs targets found' > > > +else > > > + message = 'Building docs:' > > > +endif > > > +run_target('doc', command: ['echo', message, doc_target_names], > > > + depends: doc_targets) > > > > One thing that's missing is the install_dir, without which ninja > > install doesn't work (actually errors out for the whole tree). > > > > To keep the install the same as the legacy makefiles this diff is > > needed (I need to change the outdir in the doxygen stuff too, v5 > > coming) (in the build dir it will be slightly awkward as it's > > build/doc/guides/guides and build/doc/api/api, but I can't find > > another > > way to get it to work and install in the expected directories): > > > > --- a/doc/guides/meson.build > > +++ b/doc/guides/meson.build > > @@ -4,12 +4,14 @@ > >  sphinx = find_program('sphinx-build', required: > > get_option('enable_docs')) > >   > >  if sphinx.found() > > +       htmldir = join_paths('share', 'doc', 'dpdk') > >         html_guides_build = custom_target('html_guides_build', > >                 input: meson.current_source_dir(), > > -               output: 'index.html', > > -               command: [sphinx, '-b', 'html', '@INPUT@', > > meson.current_build_dir() + '/html'], > > +               output: 'guides', > > +               command: [sphinx, '-b', 'html', '@INPUT@', > > meson.current_build_dir() + '/guides'], > >                 build_by_default: false, > > -               install: get_option('enable_docs')) > > +               install: get_option('enable_docs'), > > +               install_dir: htmldir) > >   > >         doc_targets += html_guides_build > >         doc_target_names += 'HTML_Guides' > > Couple more issues: I diffed the installed doc with ye olde make and > this one, and: > > 1) This one will install sphinx temporary cache files, which among > other things will screw up reproducible builds. It's easy to get rid of > the .doctrees by adding the following to the sphinx command: > > '-d', meson.current_build_dir() + '/.doctrees' > > so that the doctrees are stored in the build directory, rather than in > the output directory, and so they will not be installed. > But the .buildinfo file, with some hashes (and so more reproducibility > problems) is still installed and I can't see how to get rid of it. > > 2) The custom.css file is installed manually by ye olde makefiles and > thus is missing from guides/_static/css/custom.css > Great, thanks for all the reviews. I'll attempt to fix as much as possible and do a V2. /Bruce