DPDK patches and discussions
 help / color / mirror / Atom feed
From: Luca Boccassi <bluca@debian.org>
To: Bruce Richardson <bruce.richardson@intel.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson
Date: Wed, 12 Sep 2018 10:48:15 +0100	[thread overview]
Message-ID: <1536745695.10952.39.camel@debian.org> (raw)
In-Reply-To: <20180912093600.GB15632@bricha3-MOBL.ger.corp.intel.com>

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 <bruce.richardson@intel.com>
> > > > ---
> > > > 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 <bluca@debian.org>
> > > >  
> > > > +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

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

-- 
Kind regards,
Luca Boccassi

  reply	other threads:[~2018-09-12  9:48 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-09-11 16:13 Bruce Richardson
2018-09-11 20:36 ` Luca Boccassi
2018-09-11 21:47   ` Luca Boccassi
2018-09-12  9:36     ` Bruce Richardson
2018-09-12  9:48       ` Luca Boccassi [this message]
2018-09-12 10:13         ` Bruce Richardson
2018-09-12 12:08           ` Luca Boccassi
2018-09-19 13:48 ` [dpdk-dev] [PATCH v2] " Luca Boccassi
2018-09-20 13:19   ` Timothy Redaelli
2018-09-20 13:22 ` [dpdk-dev] [PATCH v3] " Luca Boccassi
2018-09-20 13:51   ` Timothy Redaelli
2018-10-27 21:54     ` Thomas Monjalon
2018-10-29 10:01       ` Luca Boccassi

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1536745695.10952.39.camel@debian.org \
    --to=bluca@debian.org \
    --cc=bruce.richardson@intel.com \
    --cc=dev@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).