motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-04 00:03:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Build and install all the docs in a single manual

Browse source 
When we first converted our documentation to Sphinx, we split it into
multiple manuals (system, interop, tools, etc), which are all built
separately.  The primary driver for this was wanting to be able to
avoid shipping the 'devel' manual to end-users.  However, this is
working against the grain of the way Sphinx wants to be used and
causes some annoyances:
 * Cross-references between documents become much harder or
   possibly impossible
 * There is no single index to the whole documentation
 * Within one manual there's no links or table-of-contents info
   that lets you easily navigate to the others
 * The devel manual doesn't get published on the QEMU website
   (it would be nice to able to refer to it there)

Merely hiding our developer documentation from end users seems like
it's not enough benefit for these costs.  Combine all the
documentation into a single manual (the same way that the readthedocs
site builds it) and install the whole thing.  The previous manual
divisions remain as the new top level sections in the manual.

 * The per-manual conf.py files are no longer needed
 * The man_pages[] specifications previously in each per-manual
   conf.py move to the top level conf.py
 * docs/meson.build logic is simplified as we now only need to run
   Sphinx once for the HTML and then once for the manpages5B
 * The old index.html.in that produced the top-level page with
   links to each manual is no longer needed

Unfortunately this means that we now have to build the HTML
documentation into docs/manual in the build tree rather than directly
into docs/; otherwise it is too awkward to ensure we install only the
built manual and not also the dependency info, stamp file, etc.  The
manual still ends up in the same place in the final installed
directory, but anybody who was consulting documentation from within
the build tree will have to adjust where they're looking.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-id: 20210115154449.4801-1-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2021-01-15 15:44:49 +00:00
parent 0ae4f11ee5
commit b93f4fbdc4
10 changed files with 72 additions and 198 deletions
Download patch file Download diff file Expand all files Collapse all files

64
docs/meson.build
View file

@ -46,19 +46,11 @@ if build_docs
meson.source_root() / 'docs/sphinx/qmp_lexer.py',
qapi_gen_depends ]
configure_file(output: 'index.html',
input: files('index.html.in'),
configuration: {'VERSION': meson.project_version()},
install_dir: qemu_docdir)
manuals = [ 'devel', 'interop', 'tools', 'specs', 'system', 'user' ]
man_pages = {
'interop' : {
'qemu-ga.8': (have_tools ? 'man8' : ''),
'qemu-ga-ref.7': 'man7',
'qemu-qmp-ref.7': 'man7',
'qemu-storage-daemon-qmp-ref.7': (have_tools ? 'man7' : ''),
},
'tools': {
'qemu-img.1': (have_tools ? 'man1' : ''),
'qemu-nbd.8': (have_tools ? 'man8' : ''),
'qemu-pr-helper.8': (have_tools ? 'man8' : ''),
@ -66,53 +58,47 @@ if build_docs
'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''),
'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''),
'virtiofsd.1': (have_virtiofsd ? 'man1' : ''),
},
'system': {
'qemu.1': 'man1',
'qemu-block-drivers.7': 'man7',
'qemu-cpu-models.7': 'man7'
},
}
sphinxdocs = []
sphinxmans = []
foreach manual : manuals
private_dir = meson.current_build_dir() / (manual + '.p')
output_dir = meson.current_build_dir() / manual
input_dir = meson.current_source_dir() / manual
this_manual = custom_target(manual + ' manual',
private_dir = meson.current_build_dir() / 'manual.p'
output_dir = meson.current_build_dir() / 'manual'
input_dir = meson.current_source_dir()
this_manual = custom_target('QEMU manual',
build_by_default: build_docs,
output: [manual + '.stamp'],
input: [files('conf.py'), files(manual / 'conf.py')],
depfile: manual + '.d',
output: 'docs.stamp',
input: files('conf.py'),
depfile: 'docs.d',
depend_files: sphinx_extn_depends,
command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
'-Ddepfile_stamp=@OUTPUT0@',
'-b', 'html', '-d', private_dir,
input_dir, output_dir])
sphinxdocs += this_manual
if build_docs and manual != 'devel'
install_subdir(output_dir, install_dir: qemu_docdir)
endif
sphinxdocs += this_manual
install_subdir(output_dir, install_dir: qemu_docdir, strip_directory: true)
these_man_pages = []
install_dirs = []
foreach page, section : man_pages.get(manual, {})
these_man_pages += page
install_dirs += section == '' ? false : get_option('mandir') / section
endforeach
if these_man_pages.length() > 0
sphinxmans += custom_target(manual + ' man pages',
build_by_default: build_docs,
output: these_man_pages,
input: this_manual,
install: build_docs,
install_dir: install_dirs,
command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir,
input_dir, meson.current_build_dir()])
endif
these_man_pages = []
install_dirs = []
foreach page, section : man_pages
these_man_pages += page
install_dirs += section == '' ? false : get_option('mandir') / section
endforeach
sphinxmans += custom_target('QEMU man pages',
build_by_default: build_docs,
output: these_man_pages,
input: this_manual,
install: build_docs,
install_dir: install_dirs,
command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir,
input_dir, meson.current_build_dir()])
alias_target('sphinxdocs', sphinxdocs)
alias_target('html', sphinxdocs)
alias_target('man', sphinxmans)