* [dpdk-dev] [PATCH] doc: support building HTML guides with meson
@ 2018-09-11 16:13 Bruce Richardson
2018-09-11 20:36 ` Luca Boccassi
` (2 more replies)
0 siblings, 3 replies; 13+ messages in thread
From: Bruce Richardson @ 2018-09-11 16:13 UTC (permalink / raw)
To: bluca; +Cc: dev, Bruce Richardson
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
NOTE: this patch depends upon:
http://patches.dpdk.org/project/dpdk/list/?series=1232
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
+
+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',
+ 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)
--
2.11.0
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-11 16:13 [dpdk-dev] [PATCH] doc: support building HTML guides with meson Bruce Richardson @ 2018-09-11 20:36 ` Luca Boccassi 2018-09-11 21:47 ` Luca Boccassi 2018-09-19 13:48 ` [dpdk-dev] [PATCH v2] " Luca Boccassi 2018-09-20 13:22 ` [dpdk-dev] [PATCH v3] " Luca Boccassi 2 siblings, 1 reply; 13+ messages in thread From: Luca Boccassi @ 2018-09-11 20:36 UTC (permalink / raw) To: Bruce Richardson; +Cc: dev 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' -- Kind regards, Luca Boccassi ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-11 20:36 ` Luca Boccassi @ 2018-09-11 21:47 ` Luca Boccassi 2018-09-12 9:36 ` Bruce Richardson 0 siblings, 1 reply; 13+ messages in thread From: Luca Boccassi @ 2018-09-11 21:47 UTC (permalink / raw) To: Bruce Richardson; +Cc: dev 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 -- Kind regards, Luca Boccassi ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-11 21:47 ` Luca Boccassi @ 2018-09-12 9:36 ` Bruce Richardson 2018-09-12 9:48 ` Luca Boccassi 0 siblings, 1 reply; 13+ messages in thread From: Bruce Richardson @ 2018-09-12 9:36 UTC (permalink / raw) To: Luca Boccassi; +Cc: dev 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-12 9:36 ` Bruce Richardson @ 2018-09-12 9:48 ` Luca Boccassi 2018-09-12 10:13 ` Bruce Richardson 0 siblings, 1 reply; 13+ messages in thread From: Luca Boccassi @ 2018-09-12 9:48 UTC (permalink / raw) To: Bruce Richardson; +Cc: dev 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-12 9:48 ` Luca Boccassi @ 2018-09-12 10:13 ` Bruce Richardson 2018-09-12 12:08 ` Luca Boccassi 0 siblings, 1 reply; 13+ messages in thread From: Bruce Richardson @ 2018-09-12 10:13 UTC (permalink / raw) To: Luca Boccassi; +Cc: dev 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 <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 > Just to check that I see what you see, what are the commands you are using to compare the old vs new docs? /Bruce ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH] doc: support building HTML guides with meson 2018-09-12 10:13 ` Bruce Richardson @ 2018-09-12 12:08 ` Luca Boccassi 0 siblings, 0 replies; 13+ messages in thread From: Luca Boccassi @ 2018-09-12 12:08 UTC (permalink / raw) To: Bruce Richardson; +Cc: dev 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 <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 > > > > Just to check that I see what you see, what are the commands you are > using > to compare the old vs new docs? > > /Bruce I'm tarring up the installed share/dpdk/doc directory (with: GZIP="- 9fn" tar --sort=name --mtime="@1534269491" --clamp-mtime --owner=0 -- group=0 --numeric-owner -czf ) and then using diffoscope on them, which will compare everything down to the bytes :-) -- Kind regards, Luca Boccassi ^ permalink raw reply [flat|nested] 13+ messages in thread
* [dpdk-dev] [PATCH v2] doc: support building HTML guides with meson 2018-09-11 16:13 [dpdk-dev] [PATCH] doc: support building HTML guides with meson Bruce Richardson 2018-09-11 20:36 ` Luca Boccassi @ 2018-09-19 13:48 ` Luca Boccassi 2018-09-20 13:19 ` Timothy Redaelli 2018-09-20 13:22 ` [dpdk-dev] [PATCH v3] " Luca Boccassi 2 siblings, 1 reply; 13+ messages in thread From: Luca Boccassi @ 2018-09-19 13:48 UTC (permalink / raw) To: dev; +Cc: bruce.richardson, Luca Boccassi From: Bruce Richardson <bruce.richardson@intel.com> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> Signed-off-by: Luca Boccassi <bluca@debian.org> --- v2: send on behalf of Bruce on request. - tell sphinx to create .doctrees working files in the parent of the target directory so that they don't get installed - change the output directory so that it matches the legacy makefiles directory structure (on install) - add install_dir to fix ninja install - add post-install calls to delete .buildinfo sphinx temporary file and to install custom.css as the makefiles do The installed directory has been verified to be bit-by-bit identical to the legacy makefiles with diffoscope. doc/api/meson.build | 5 ++--- doc/guides/meson.build | 27 +++++++++++++++++++++++++++ doc/meson.build | 11 +++++++++++ 3 files changed, 40 insertions(+), 3 deletions(-) create mode 100644 doc/guides/meson.build diff --git a/doc/api/meson.build b/doc/api/meson.build index 13fcbb8cd7..30bdc573b5 100644 --- a/doc/api/meson.build +++ b/doc/api/meson.build @@ -50,7 +50,6 @@ if doxygen.found() install_dir: htmldir, build_by_default: false) - run_target('doc', command: 'true', depends: doxy_build) -else - run_target('doc', command: ['echo', 'doxygen', 'not', 'found']) + 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 0000000000..24f5316c5c --- /dev/null +++ b/doc/guides/meson.build @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Intel Corporation + +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: 'guides', + command: [sphinx, '-b', 'html', '@INPUT@', meson.current_build_dir() + '/guides', + '-d', meson.current_build_dir() + '/.doctrees'], + build_by_default: false, + install: get_option('enable_docs'), + install_dir: htmldir) + + doc_targets += html_guides_build + doc_target_names += 'HTML_Guides' + + # sphinx leaves a .buildinfo in the target directory, which we don't + # want to install. Note that sh -c has to be used, otherwise the + # env var does not get expanded if calling rm/install directly. + meson.add_install_script('sh', '-c', + 'rm -f $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/.buildinfo') + meson.add_install_script('sh', '-c', + 'install -D -m0644 $MESON_SOURCE_ROOT/doc/guides/custom.css $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/_static/css/') +endif diff --git a/doc/meson.build b/doc/meson.build index afca2e7133..c5410d85d6 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) -- 2.18.0 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH v2] doc: support building HTML guides with meson 2018-09-19 13:48 ` [dpdk-dev] [PATCH v2] " Luca Boccassi @ 2018-09-20 13:19 ` Timothy Redaelli 0 siblings, 0 replies; 13+ messages in thread From: Timothy Redaelli @ 2018-09-20 13:19 UTC (permalink / raw) To: Luca Boccassi; +Cc: dev, bruce.richardson On Wed, 19 Sep 2018 14:48:27 +0100 Luca Boccassi <bluca@debian.org> wrote: > From: Bruce Richardson <bruce.richardson@intel.com> > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> > Signed-off-by: Luca Boccassi <bluca@debian.org> > --- > v2: send on behalf of Bruce on request. > - tell sphinx to create .doctrees working files in the > parent of the target directory so that they don't get > installed > - change the output directory so that it matches the legacy > makefiles directory structure (on install) > - add install_dir to fix ninja install > - add post-install calls to delete .buildinfo sphinx > temporary file and to install custom.css as the makefiles > do > The installed directory has been verified to be bit-by-bit > identical to the legacy makefiles with diffoscope. > > doc/api/meson.build | 5 ++--- > doc/guides/meson.build | 27 +++++++++++++++++++++++++++ > doc/meson.build | 11 +++++++++++ > 3 files changed, 40 insertions(+), 3 deletions(-) > create mode 100644 doc/guides/meson.build > > diff --git a/doc/api/meson.build b/doc/api/meson.build > index 13fcbb8cd7..30bdc573b5 100644 > --- a/doc/api/meson.build > +++ b/doc/api/meson.build > @@ -50,7 +50,6 @@ if doxygen.found() > install_dir: htmldir, > build_by_default: false) > > - run_target('doc', command: 'true', depends: doxy_build) > -else > - run_target('doc', command: ['echo', 'doxygen', 'not', 'found']) > + 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 0000000000..24f5316c5c > --- /dev/null > +++ b/doc/guides/meson.build > @@ -0,0 +1,27 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2018 Intel Corporation > + > +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: 'guides', > + command: [sphinx, '-b', 'html', '@INPUT@', meson.current_build_dir() + '/guides', > + '-d', meson.current_build_dir() + '/.doctrees'], This on RHEL 7.5 doesn't work, since old versions of sphinx (I have v1.1.3) need all options before the paths. I tried to move "'-d', meson.current_build_dir() + '/.doctrees'" before "'@INPUT@'" and it worked. > + build_by_default: false, > + install: get_option('enable_docs'), > + install_dir: htmldir) > + > + doc_targets += html_guides_build > + doc_target_names += 'HTML_Guides' > + > + # sphinx leaves a .buildinfo in the target directory, which we don't > + # want to install. Note that sh -c has to be used, otherwise the > + # env var does not get expanded if calling rm/install directly. > + meson.add_install_script('sh', '-c', > + 'rm -f $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/.buildinfo') > + meson.add_install_script('sh', '-c', > + 'install -D -m0644 $MESON_SOURCE_ROOT/doc/guides/custom.css $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/_static/css/') This on RHEL 7.5 doesn't work. I had to append custom.css to DEST ($MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/_static/css/custom.css) to make it work. > +endif > diff --git a/doc/meson.build b/doc/meson.build > index afca2e7133..c5410d85d6 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) ^ permalink raw reply [flat|nested] 13+ messages in thread
* [dpdk-dev] [PATCH v3] doc: support building HTML guides with meson 2018-09-11 16:13 [dpdk-dev] [PATCH] doc: support building HTML guides with meson Bruce Richardson 2018-09-11 20:36 ` Luca Boccassi 2018-09-19 13:48 ` [dpdk-dev] [PATCH v2] " Luca Boccassi @ 2018-09-20 13:22 ` Luca Boccassi 2018-09-20 13:51 ` Timothy Redaelli 2 siblings, 1 reply; 13+ messages in thread From: Luca Boccassi @ 2018-09-20 13:22 UTC (permalink / raw) To: dev; +Cc: bruce.richardson, tredaelli, Luca Boccassi From: Bruce Richardson <bruce.richardson@intel.com> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> Signed-off-by: Luca Boccassi <bluca@debian.org> --- v2: send on behalf of Bruce on request. - tell sphinx to create .doctrees working files in the parent of the target directory so that they don't get installed - change the output directory so that it matches the legacy makefiles directory structure (on install) - add install_dir to fix ninja install - add post-install calls to delete .buildinfo sphinx temporary file and to install custom.css as the makefiles do The installed directory has been verified to be bit-by-bit identical to the legacy makefiles with diffoscope. v3: re-arranged sphinx parameters to make it work on older versions (RHEL 7), and specify DEST filename on the install call, to make it work on older version (RHEL 7) doc/api/meson.build | 5 ++--- doc/guides/meson.build | 28 ++++++++++++++++++++++++++++ doc/meson.build | 11 +++++++++++ 3 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 doc/guides/meson.build diff --git a/doc/api/meson.build b/doc/api/meson.build index 13fcbb8cd7..30bdc573b5 100644 --- a/doc/api/meson.build +++ b/doc/api/meson.build @@ -50,7 +50,6 @@ if doxygen.found() install_dir: htmldir, build_by_default: false) - run_target('doc', command: 'true', depends: doxy_build) -else - run_target('doc', command: ['echo', 'doxygen', 'not', 'found']) + 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 0000000000..06f14882bb --- /dev/null +++ b/doc/guides/meson.build @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Intel Corporation + +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: 'guides', + command: [sphinx, '-b', 'html', + '-d', meson.current_build_dir() + '/.doctrees', + '@INPUT@', meson.current_build_dir() + '/guides'], + build_by_default: false, + install: get_option('enable_docs'), + install_dir: htmldir) + + doc_targets += html_guides_build + doc_target_names += 'HTML_Guides' + + # sphinx leaves a .buildinfo in the target directory, which we don't + # want to install. Note that sh -c has to be used, otherwise the + # env var does not get expanded if calling rm/install directly. + meson.add_install_script('sh', '-c', + 'rm -f $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/.buildinfo') + meson.add_install_script('sh', '-c', + 'install -D -m0644 $MESON_SOURCE_ROOT/doc/guides/custom.css $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/_static/css/custom.css') +endif diff --git a/doc/meson.build b/doc/meson.build index afca2e7133..c5410d85d6 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) -- 2.18.0 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH v3] doc: support building HTML guides with meson 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 0 siblings, 1 reply; 13+ messages in thread From: Timothy Redaelli @ 2018-09-20 13:51 UTC (permalink / raw) To: Luca Boccassi; +Cc: dev, bruce.richardson On Thu, 20 Sep 2018 14:22:08 +0100 Luca Boccassi <bluca@debian.org> wrote: > From: Bruce Richardson <bruce.richardson@intel.com> > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> > Signed-off-by: Luca Boccassi <bluca@debian.org> Tested on Fedora 28 (sphinx 1.7.5) and RHEL 7.5 (sphinx 1.1.3) Tested-by: Timothy Redaelli <tredaelli@redhat.com> ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH v3] doc: support building HTML guides with meson 2018-09-20 13:51 ` Timothy Redaelli @ 2018-10-27 21:54 ` Thomas Monjalon 2018-10-29 10:01 ` Luca Boccassi 0 siblings, 1 reply; 13+ messages in thread From: Thomas Monjalon @ 2018-10-27 21:54 UTC (permalink / raw) To: Luca Boccassi, bruce.richardson; +Cc: dev, Timothy Redaelli 20/09/2018 15:51, Timothy Redaelli: > On Thu, 20 Sep 2018 14:22:08 +0100 > Luca Boccassi <bluca@debian.org> wrote: > > > From: Bruce Richardson <bruce.richardson@intel.com> > > > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> > > Signed-off-by: Luca Boccassi <bluca@debian.org> > > Tested on Fedora 28 (sphinx 1.7.5) and RHEL 7.5 (sphinx 1.1.3) > > Tested-by: Timothy Redaelli <tredaelli@redhat.com> Applied, thanks In the build directory, docs are in - doc/api/api/ - doc/guides/guides/ Why having the last level of (redundant) directory? ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [dpdk-dev] [PATCH v3] doc: support building HTML guides with meson 2018-10-27 21:54 ` Thomas Monjalon @ 2018-10-29 10:01 ` Luca Boccassi 0 siblings, 0 replies; 13+ messages in thread From: Luca Boccassi @ 2018-10-29 10:01 UTC (permalink / raw) To: Thomas Monjalon, bruce.richardson; +Cc: dev, Timothy Redaelli On Sat, 2018-10-27 at 23:54 +0200, Thomas Monjalon wrote: > 20/09/2018 15:51, Timothy Redaelli: > > On Thu, 20 Sep 2018 14:22:08 +0100 > > Luca Boccassi <bluca@debian.org> wrote: > > > > > From: Bruce Richardson <bruce.richardson@intel.com> > > > > > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com> > > > Signed-off-by: Luca Boccassi <bluca@debian.org> > > > > Tested on Fedora 28 (sphinx 1.7.5) and RHEL 7.5 (sphinx 1.1.3) > > > > Tested-by: Timothy Redaelli <tredaelli@redhat.com> > > Applied, thanks > > In the build directory, docs are in > - doc/api/api/ > - doc/guides/guides/ > Why having the last level of (redundant) directory? Quirks due to the intersection of Meson and Sphinx/Doxygen and theirs respective quirks - it needs to be a new directory, and it needs to be called "guides/api" as that's what gets installed via ninja install. Yes it's not the prettiest in the build tree - suggestions to improve it are most welcome of course -- Kind regards, Luca Boccassi ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2018-10-29 10:01 UTC | newest] Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-09-11 16:13 [dpdk-dev] [PATCH] doc: support building HTML guides with meson 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 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
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).