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

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

  reply	other threads:[~2018-09-12  9:36 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 [this message]
2018-09-12  9:48       ` Luca Boccassi
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=20180912093600.GB15632@bricha3-MOBL.ger.corp.intel.com \
    --to=bruce.richardson@intel.com \
    --cc=bluca@debian.org \
    --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

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git