[v3,5/6] doc/guides: rebuild with meson whenever a file changes
Checks
Commit Message
Add proper support for calling sphinx whenever a file in the doc
directory changes. This is accomplished by using a wrapper script
for sphinx, which runs sphinx but also emits a gcc-format dependency
file listing all the doc files. This is used by ninja so that any
change to the doc files triggers a rebuild of the docs.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Aaron Conole <aconole@redhat.com>
---
buildtools/call-sphinx-build.py | 23 +++++++++++++++++++++++
buildtools/meson.build | 6 ++++--
doc/guides/meson.build | 22 ++++++++--------------
3 files changed, 35 insertions(+), 16 deletions(-)
create mode 100755 buildtools/call-sphinx-build.py
Comments
On Thu, Jan 9, 2020 at 4:31 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> Add proper support for calling sphinx whenever a file in the doc
> directory changes. This is accomplished by using a wrapper script
> for sphinx, which runs sphinx but also emits a gcc-format dependency
> file listing all the doc files. This is used by ninja so that any
> change to the doc files triggers a rebuild of the docs.
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Acked-by: Aaron Conole <aconole@redhat.com>
> ---
> buildtools/call-sphinx-build.py | 23 +++++++++++++++++++++++
> buildtools/meson.build | 6 ++++--
> doc/guides/meson.build | 22 ++++++++--------------
> 3 files changed, 35 insertions(+), 16 deletions(-)
> create mode 100755 buildtools/call-sphinx-build.py
This new file is not added to MAINTAINERS.
--
David Marchand
On Thu, Jan 9, 2020 at 7:03 PM David Marchand <david.marchand@redhat.com> wrote:
>
> On Thu, Jan 9, 2020 at 4:31 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > Add proper support for calling sphinx whenever a file in the doc
> > directory changes. This is accomplished by using a wrapper script
> > for sphinx, which runs sphinx but also emits a gcc-format dependency
> > file listing all the doc files. This is used by ninja so that any
> > change to the doc files triggers a rebuild of the docs.
> >
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > Acked-by: Aaron Conole <aconole@redhat.com>
> > ---
> > buildtools/call-sphinx-build.py | 23 +++++++++++++++++++++++
> > buildtools/meson.build | 6 ++++--
> > doc/guides/meson.build | 22 ++++++++--------------
> > 3 files changed, 35 insertions(+), 16 deletions(-)
> > create mode 100755 buildtools/call-sphinx-build.py
>
> This new file is not added to MAINTAINERS.
I can fix this when applying.
I would add this to the section:
Meson build
M: Bruce Richardson <bruce.richardson@intel.com>
On Thu, Jan 09, 2020 at 07:06:31PM +0100, David Marchand wrote:
> On Thu, Jan 9, 2020 at 7:03 PM David Marchand <david.marchand@redhat.com> wrote:
> >
> > On Thu, Jan 9, 2020 at 4:31 PM Bruce Richardson
> > <bruce.richardson@intel.com> wrote:
> > >
> > > Add proper support for calling sphinx whenever a file in the doc
> > > directory changes. This is accomplished by using a wrapper script
> > > for sphinx, which runs sphinx but also emits a gcc-format dependency
> > > file listing all the doc files. This is used by ninja so that any
> > > change to the doc files triggers a rebuild of the docs.
> > >
> > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > > Acked-by: Aaron Conole <aconole@redhat.com>
> > > ---
> > > buildtools/call-sphinx-build.py | 23 +++++++++++++++++++++++
> > > buildtools/meson.build | 6 ++++--
> > > doc/guides/meson.build | 22 ++++++++--------------
> > > 3 files changed, 35 insertions(+), 16 deletions(-)
> > > create mode 100755 buildtools/call-sphinx-build.py
> >
> > This new file is not added to MAINTAINERS.
>
> I can fix this when applying.
> I would add this to the section:
>
> Meson build
> M: Bruce Richardson <bruce.richardson@intel.com>
>
Agreed.
On Thu, Jan 09, 2020 at 03:31:11PM +0000, Bruce Richardson wrote:
> Add proper support for calling sphinx whenever a file in the doc
> directory changes. This is accomplished by using a wrapper script
> for sphinx, which runs sphinx but also emits a gcc-format dependency
> file listing all the doc files. This is used by ninja so that any
> change to the doc files triggers a rebuild of the docs.
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Acked-by: Aaron Conole <aconole@redhat.com>
> ---
> buildtools/call-sphinx-build.py | 23 +++++++++++++++++++++++
> buildtools/meson.build | 6 ++++--
> doc/guides/meson.build | 22 ++++++++--------------
> 3 files changed, 35 insertions(+), 16 deletions(-)
> create mode 100755 buildtools/call-sphinx-build.py
>
> diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
> new file mode 100755
> index 000000000..80bda2661
> --- /dev/null
> +++ b/buildtools/call-sphinx-build.py
> @@ -0,0 +1,23 @@
> +#! /usr/bin/env python3
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2019 Intel Corporation
> +#
> +
> +import sys
> +import os
> +from os.path import join
> +from subprocess import run
> +
> +(sphinx, src, dst) = sys.argv[1:] # assign parameters to variables
> +
> +# find all the files sphinx will process so we can write them as dependencies
> +srcfiles = []
> +for root, dirs, files in os.walk(src):
> + srcfiles.extend([join(root, f) for f in files])
> +
> +# run sphinx, putting the html output in a "html" directory
> +run([sphinx, '-j', 'auto', '-b', 'html', src, join(dst, 'html')], check=True)
> +
Looking in travis, it appears that sphinx there is too old to support the
"-j auto" flag, so I'll do a new revision to fix that.
/Bruce
new file mode 100755
@@ -0,0 +1,23 @@
+#! /usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2019 Intel Corporation
+#
+
+import sys
+import os
+from os.path import join
+from subprocess import run
+
+(sphinx, src, dst) = sys.argv[1:] # assign parameters to variables
+
+# find all the files sphinx will process so we can write them as dependencies
+srcfiles = []
+for root, dirs, files in os.walk(src):
+ srcfiles.extend([join(root, f) for f in files])
+
+# run sphinx, putting the html output in a "html" directory
+run([sphinx, '-j', 'auto', '-b', 'html', src, join(dst, 'html')], check=True)
+
+# create a gcc format .d file giving all the dependencies of this doc build
+with open(join(dst, '.html.d'), 'w') as d:
+ d.write('html: ' + ' '.join(srcfiles) + '\n')
@@ -10,10 +10,12 @@ check_experimental_syms = find_program('check-experimental-syms.sh')
# set up map-to-def script using python, either built-in or external
python3 = import('python').find_installation(required: false)
if python3.found()
- map_to_def_cmd = [python3, files('map_to_def.py')]
+ py3 = [python3]
else
- map_to_def_cmd = ['meson', 'runpython', files('map_to_def.py')]
+ py3 = ['meson', 'runpython']
endif
+map_to_def_cmd = py3 + files('map_to_def.py')
+sphinx_wrapper = py3 + files('call-sphinx-build.py')
# stable ABI always starts with "DPDK_"
is_experimental_cmd = [find_program('grep', 'findstr'), '^DPDK_']
@@ -7,24 +7,18 @@ if not sphinx.found()
subdir_done()
endif
-htmldir = join_paths('share', 'doc', 'dpdk')
+htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
html_guides = custom_target('html_guides',
- input: meson.current_source_dir(),
- output: 'guides',
- command: [sphinx, '-b', 'html',
- '-d', meson.current_build_dir() + '/.doctrees',
- '@INPUT@', meson.current_build_dir() + '/guides'],
+ input: files('index.rst'),
+ output: 'html',
+ command: [sphinx_wrapper, sphinx, meson.current_source_dir(), meson.current_build_dir()],
+ depfile: '.html.d',
build_by_default: get_option('enable_docs'),
install: get_option('enable_docs'),
install_dir: htmldir)
+install_data(files('custom.css'),
+ install_dir: join_paths(htmldir,'_static', 'css'))
+
doc_targets += html_guides
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')