| Message ID | 20200925162316.21205-15-peter.maydell@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@linaro.org> writes: > The automatic dependency handling for Sphinx manuals only makes the output > depend on the input documentation files. This means that if you edit > the Python source of an extension then the documentation won't be > rebuilt. > > Create a list of all the source files for the extensions and add > it to the dependencies for the manuals. This is similar to how we > handle the qapi_gen_depends list. > > Because we don't try to identify which manuals are using which > Sphinx extensions, a change to the source of one extension will > always rebuild the entire manual set, not merely the manuals > which have changed. This is acceptable because we don't change > the extensions all that often. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > docs/meson.build | 1 + > meson.build | 8 ++++++++ > 2 files changed, 9 insertions(+) > > diff --git a/docs/meson.build b/docs/meson.build > index 99da609e813..59fea873b10 100644 > --- a/docs/meson.build > +++ b/docs/meson.build > @@ -36,6 +36,7 @@ if build_docs > output: [manual + '.stamp'], > input: [files('conf.py'), files(manual / 'conf.py')], > depfile: manual + '.d', > + depend_files: sphinx_extn_depends, > command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@', > '-Ddepfile_stamp=@OUTPUT0@', > '-b', 'html', '-d', private_dir, > diff --git a/meson.build b/meson.build > index 6408ad442ea..3c07e75dbd5 100644 > --- a/meson.build > +++ b/meson.build > @@ -679,6 +679,14 @@ if get_option('werror') > SPHINX_ARGS += [ '-W' ] > endif > > +sphinx_extn_depends = [ meson.source_root() / 'docs/sphinx/depfile.py', > + meson.source_root() / 'docs/sphinx/hxtool.py', > + meson.source_root() / 'docs/sphinx/kerneldoc.py', > + meson.source_root() / 'docs/sphinx/kernellog.py', > + meson.source_root() / 'docs/sphinx/qapidoc.py', > + meson.source_root() / 'docs/sphinx/qmp_lexer.py', > + qapi_gen_depends ] > + > # Collect sourcesets. > > util_ss = ss.source_set() I touched docs/sphinx/qapidoc.py and the manual got rebuilt. Good. Same for scripts/qapi/gen.py. Good, except it makes me disbelieve your claim "we don't change the extensions all that often." Any ideas beyond amending the commit message with something like "except for the QAPI guys, pity the fools"? ;)
diff --git a/docs/meson.build b/docs/meson.build index 99da609e813..59fea873b10 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -36,6 +36,7 @@ if build_docs output: [manual + '.stamp'], input: [files('conf.py'), files(manual / 'conf.py')], depfile: manual + '.d', + depend_files: sphinx_extn_depends, command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@', '-Ddepfile_stamp=@OUTPUT0@', '-b', 'html', '-d', private_dir, diff --git a/meson.build b/meson.build index 6408ad442ea..3c07e75dbd5 100644 --- a/meson.build +++ b/meson.build @@ -679,6 +679,14 @@ if get_option('werror') SPHINX_ARGS += [ '-W' ] endif +sphinx_extn_depends = [ meson.source_root() / 'docs/sphinx/depfile.py', + meson.source_root() / 'docs/sphinx/hxtool.py', + meson.source_root() / 'docs/sphinx/kerneldoc.py', + meson.source_root() / 'docs/sphinx/kernellog.py', + meson.source_root() / 'docs/sphinx/qapidoc.py', + meson.source_root() / 'docs/sphinx/qmp_lexer.py', + qapi_gen_depends ] + # Collect sourcesets. util_ss = ss.source_set()
The automatic dependency handling for Sphinx manuals only makes the output depend on the input documentation files. This means that if you edit the Python source of an extension then the documentation won't be rebuilt. Create a list of all the source files for the extensions and add it to the dependencies for the manuals. This is similar to how we handle the qapi_gen_depends list. Because we don't try to identify which manuals are using which Sphinx extensions, a change to the source of one extension will always rebuild the entire manual set, not merely the manuals which have changed. This is acceptable because we don't change the extensions all that often. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- docs/meson.build | 1 + meson.build | 8 ++++++++ 2 files changed, 9 insertions(+)