From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm0-f67.google.com (mail-wm0-f67.google.com [74.125.82.67]) by dpdk.org (Postfix) with ESMTP id 6007D4C94 for ; Wed, 12 Sep 2018 14:08:47 +0200 (CEST) Received: by mail-wm0-f67.google.com with SMTP id c14-v6so2118941wmb.4 for ; Wed, 12 Sep 2018 05:08:47 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:message-id:subject:from:to:cc:date:in-reply-to :references:content-transfer-encoding:mime-version; bh=byaPh45dB3W+6igWUBRzDXpcldSatHZYZF9G3oToIIU=; b=ZnC/KD6865ETvWcTqVIm6rudyiTRdKfRhZyoticQee3I6FdWeefGljmCfxXP4oTdyE 29flZ2cR0KWidf9dYs/mUfE7hA3hksreIMoLmO9gphvIX0XaVYXAqf8MTmp1gB67r1Dp JM753bxX9Kh51yJv2LPyYqapQVqNVb+McyAu5BOzP8kT1fPLU+HuPGaHavLvhUeEMdJM 2NLnFscqnFuF2WE1DKzamP1HN2mSA/dhlCpFDfvM693+qfYlv1v16Q2Cw45KnlkznD6l kjuNVteKChJhk/1THZI2nAF5T0Vqpi4lWsP0LpIElXBCymBPdqHtEihMDFB0dFjJb53F VPgQ== X-Gm-Message-State: APzg51BPSmGmjUG3oSEKQATDpZTIk09x5Ur4T3XNbtLOn2tOEJQqMROn hzXDTXhGsKV8XQ/RTdUTBf/Qe03xA4U= X-Google-Smtp-Source: ANB0VdaizVsm8/KC/y6FXJdS0wB3zvSOmQMwGWztI5VHh4q3+f9CXcqiPzQn+2a1PjfM2TG0/AFW7w== X-Received: by 2002:a1c:3b56:: with SMTP id i83-v6mr1376494wma.66.1536754126919; Wed, 12 Sep 2018 05:08:46 -0700 (PDT) Received: from localhost ([2001:1be0:110d:fcfe:34de:1298:1768:55da]) by smtp.gmail.com with ESMTPSA id e7-v6sm1137390wru.46.2018.09.12.05.08.45 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 12 Sep 2018 05:08:45 -0700 (PDT) Message-ID: <1536754124.10952.45.camel@debian.org> From: Luca Boccassi To: Bruce Richardson Cc: dev@dpdk.org Date: Wed, 12 Sep 2018 13:08:44 +0100 In-Reply-To: <20180912101313.GA11120@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> <20180912093600.GB15632@bricha3-MOBL.ger.corp.intel.com> <1536745695.10952.39.camel@debian.org> <20180912101313.GA11120@bricha3-MOBL.ger.corp.intel.com> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Mailer: Evolution 3.22.6-1+deb9u1 Mime-Version: 1.0 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 12:08:47 -0000 On Wed, 2018-09-12 at 11:13 +0100, Bruce Richardson wrote: > On Wed, Sep 12, 2018 at 10:48:15AM +0100, Luca Boccassi wrote: > > On Wed, 2018-09-12 at 10:36 +0100, Bruce Richardson wrote: > > > 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=3D1232 > > > > >=20 > > > > > Just a reminder that's v2, and the patch won't apply cleanly > > > > > on > > > > > the > > > > > latest revision > > > > >=20 > > > > > > =C2=A0doc/api/meson.build=C2=A0=C2=A0=C2=A0=C2=A0|=C2=A0=C2=A03= ++- > > > > > > =C2=A0doc/guides/meson.build | 16 ++++++++++++++++ > > > > > > =C2=A0doc/meson.build=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0| 11 +++++++++++ > > > > > > =C2=A03 files changed, 29 insertions(+), 1 deletion(-) > > > > > > =C2=A0create mode 100644 doc/guides/meson.build > > > > > >=20 > > > > > > 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() > > > > > > =C2=A0 install_dir: htmldir, > > > > > > =C2=A0 build_by_default: false) > > > > > > =C2=A0 > > > > > > - run_target('doc', command: 'true', depends: > > > > > > doxy_build) > > > > > > + doc_targets +=3D doxy_build > > > > > > + doc_target_names +=3D 'Doxygen_API' > > > > > > =C2=A0endif > > > > > > 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 > > > > >=20 > > > > > s/2017/2018 > > > > >=20 > > > > > > +sphinx =3D find_program('sphinx-build', required: > > > > > > get_option('enable_docs')) > > > > > > + > > > > > > +if sphinx.found() > > > > > > + html_guides_build =3D > > > > > > custom_target('html_guides_build', > > > > > > + input: meson.current_source_dir(), > > > > > > + output: 'index.html', > > > > >=20 > > > > > 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=3Dtrue 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. > > > > >=20 > > > > > > + command: [sphinx, '-b', 'html', '@INPUT@', > > > > > > meson.current_build_dir() + '/html'], > > > > > > + build_by_default: false, > > > > > > + install: get_option('enable_docs')) > > > > > > + > > > > > > + doc_targets +=3D html_guides_build > > > > > > + doc_target_names +=3D '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 @@ > > > > > > =C2=A0# SPDX-License-Identifier: BSD-3-Clause > > > > > > =C2=A0# Copyright(c) 2018 Luca Boccassi > > > > > > =C2=A0 > > > > > > +doc_targets =3D [] > > > > > > +doc_target_names =3D [] > > > > > > =C2=A0subdir('api') > > > > > > +subdir('guides') > > > > > > + > > > > > > +if doc_targets.length() =3D=3D 0 > > > > > > + message =3D 'No docs targets found' > > > > > > +else > > > > > > + message =3D 'Building docs:' > > > > > > +endif > > > > > > +run_target('doc', command: ['echo', message, > > > > > > doc_target_names], > > > > > > + depends: doc_targets) > > > > >=20 > > > > > One thing that's missing is the install_dir, without which > > > > > ninja > > > > > install doesn't work (actually errors out for the whole > > > > > tree). > > > > >=20 > > > > > 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): > > > > >=20 > > > > > --- a/doc/guides/meson.build > > > > > +++ b/doc/guides/meson.build > > > > > @@ -4,12 +4,14 @@ > > > > > =C2=A0sphinx =3D find_program('sphinx-build', required: > > > > > get_option('enable_docs')) > > > > > =C2=A0 > > > > > =C2=A0if sphinx.found() > > > > > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0htmldir =3D join_paths= ('share', 'doc', 'dpdk') > > > > > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0html_guides_build= =3D > > > > > custom_target('html_guides_build', > > > > > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0input: meson.current_source_dir(), > > > > > -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0output: 'index.html', > > > > > -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0command: [sphinx, '-b', 'html', '@INPUT@', > > > > > meson.current_build_dir() + '/html'], > > > > > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0output: 'guides', > > > > > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0command: [sphinx, '-b', 'html', '@INPUT@', > > > > > meson.current_build_dir() + '/guides'], > > > > > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0build_by_default: false, > > > > > -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0install: get_option('enable_docs')) > > > > > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0install: get_option('enable_docs'), > > > > > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0install_dir: htmldir) > > > > > =C2=A0 > > > > > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0doc_targets +=3D = html_guides_build > > > > > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0doc_target_names = +=3D 'HTML_Guides' > > > >=20 > > > > Couple more issues: I diffed the installed doc with ye olde > > > > make > > > > and > > > > this one, and: > > > >=20 > > > > 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: > > > >=20 > > > > =C2=A0'-d', meson.current_build_dir() + '/.doctrees' > > > >=20 > > > > 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. > > > >=20 > > > > 2) The custom.css file is installed manually by ye olde > > > > makefiles > > > > and > > > > thus is missing from guides/_static/css/custom.css > > > >=20 > > >=20 > > > Great, thanks for all the reviews. I'll attempt to fix as much as > > > possible > > > and do a V2. > > >=20 > > > /Bruce > >=20 > > For the last 2 things, the only thing I can think of is having a > > little > > bash script like for doxygen, that calls sphinx, copies the css > > file > > and then deletes the .buildinfo. Not the cleanest, but I can't > > think of > > other options - I looked into sphinx-build and I can't see an > > option to > > determine where .buildinfo is saved to unfortunately > >=20 >=20 > Just to check that I see what you see, what are the commands you are > using > to compare the old vs new docs? >=20 > /Bruce I'm tarring up the installed share/dpdk/doc directory (with: GZIP=3D"- 9fn" tar --sort=3Dname --mtime=3D"@1534269491" --clamp-mtime --owner=3D0 -- group=3D0 --numeric-owner -czf ) and then using diffoscope on them, which will compare everything down to the bytes :-) --=20 Kind regards, Luca Boccassi