From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-f66.google.com (mail-wr1-f66.google.com [209.85.221.66]) by dpdk.org (Postfix) with ESMTP id F247B2BF9 for ; Tue, 11 Sep 2018 23:48:00 +0200 (CEST) Received: by mail-wr1-f66.google.com with SMTP id u12-v6so27503052wrr.4 for ; Tue, 11 Sep 2018 14:48:00 -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=gUMpPSmYp+Q+B2jnm5DimiePhQ/zCESvreFvg8OyoX8=; b=eNwrgSTrOlPWlwsJi22b8NexjAHsUzqdlVHUUoOnSUu6ufWRjKYWzarGWg5250ndKl k+54UzBCbqAsFigEuDaozuQaVdTByVHB/QwShrxSTdKP/u0qqMJpXIk6qcwq8D0pb4JI ALcrvRUJFUXv1uGUYccodL58kCmRPyBAzcLrMavzeDd8+RutsJEUBaW3Om+s/vjzSE/D gHY74Pt4pWQPjhu2GBtkeBfViWHOz/oW1JiIg5L76bMKoXvMToKAJA0ljPbXIh9eu3VQ xz2/zRdD80Sx1AcFWwj8gRou9xUGy+WwxVCiKbm+lBitN/EsDYWrMzZg4RAMmbZbbo7V UkZg== X-Gm-Message-State: APzg51Dup4mNkHTtm3FmLsDraD+5j1n8R2EJ0hL2RHP6wFhoMTmcxzLX vRvjNmATv1aDMBWZgd5yQYYKkWlyX4Q= X-Google-Smtp-Source: ANB0VdZtHRs5sJvojNZLUHOGGoW0mzIHaar9qb45lMwYWr6UY+keN6WnET+taNvi4b9oCNgodNaXPw== X-Received: by 2002:adf:ad34:: with SMTP id p49-v6mr21013054wrc.10.1536702480465; Tue, 11 Sep 2018 14:48:00 -0700 (PDT) Received: from localhost ([2a01:4b00:f419:6f00:8361:8946:ba2b:d556]) by smtp.gmail.com with ESMTPSA id q16-v6sm17073235wrw.2.2018.09.11.14.47.59 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 11 Sep 2018 14:47:59 -0700 (PDT) Message-ID: <1536702478.10952.36.camel@debian.org> From: Luca Boccassi To: Bruce Richardson Cc: dev@dpdk.org Date: Tue, 11 Sep 2018 22:47:58 +0100 In-Reply-To: <1536698168.10952.34.camel@debian.org> References: <20180911161322.20114-1-bruce.richardson@intel.com> <1536698168.10952.34.camel@debian.org> 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: Tue, 11 Sep 2018 21:48:01 -0000 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 cus= tom_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_gui= des_build > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0doc_target_names +=3D 'HT= ML_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 --=20 Kind regards, Luca Boccassi