| Message ID | 20191108095942.401225-3-stefanha@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: build an index page for the HTML docs | expand |
On Fri, Nov 08, 2019 at 10:59:41AM +0100, Stefan Hajnoczi wrote: > Build docs/ in a single sphinx invocation instead of treating > docs/{devel,interop,specs} separately. This allows us to build a global > index page that links to documentation across the different manuals. > > Some documentation is built outside of sphinx and is not formatted as > reStructuredText. Link directly to the .html files for the time being. > If they are converted to .rst files in the future they can be included > more elegantly. > > Sphinx wants to build all .rst files and complains if they are not > listed in the table of contents. We have not yet reviewed and > categorized some of our .rst files. Hide these files so they are always > built (and syntax-checked from now on!) but not visible in the table of > contents. Ah, nice trick. > > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> > --- > Makefile | 13 ++++--------- > docs/index.rst | 27 ++++++++++++++++++++++++++- > 2 files changed, 30 insertions(+), 10 deletions(-) Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Regards, Daniel
On Fri, 8 Nov 2019 at 09:59, Stefan Hajnoczi <stefanha@redhat.com> wrote: > > Build docs/ in a single sphinx invocation instead of treating > docs/{devel,interop,specs} separately. This allows us to build a global > index page that links to documentation across the different manuals. > > Some documentation is built outside of sphinx and is not formatted as > reStructuredText. Link directly to the .html files for the time being. > If they are converted to .rst files in the future they can be included > more elegantly. > > Sphinx wants to build all .rst files and complains if they are not > listed in the table of contents. We have not yet reviewed and > categorized some of our .rst files. Hide these files so they are always > built (and syntax-checked from now on!) but not visible in the table of > contents. So the reason I went for the odd "run sphinx multiple times" approach was because we don't want to ship 'devel' to users, and as far as I could tell there was no way to have a single-invocation build of the docs not include it in eg the index/search (which would then be broken when we don't install devel/ as part of 'make install'). Does this patchset result in a set of installed docs that don't have dangling references ? thanks -- PMM
On Fri, Nov 8, 2019 at 11:52 AM Peter Maydell <peter.maydell@linaro.org> wrote: > On Fri, 8 Nov 2019 at 09:59, Stefan Hajnoczi <stefanha@redhat.com> wrote: > > Build docs/ in a single sphinx invocation instead of treating > > docs/{devel,interop,specs} separately. This allows us to build a global > > index page that links to documentation across the different manuals. > > > > Some documentation is built outside of sphinx and is not formatted as > > reStructuredText. Link directly to the .html files for the time being. > > If they are converted to .rst files in the future they can be included > > more elegantly. > > > > Sphinx wants to build all .rst files and complains if they are not > > listed in the table of contents. We have not yet reviewed and > > categorized some of our .rst files. Hide these files so they are always > > built (and syntax-checked from now on!) but not visible in the table of > > contents. > > So the reason I went for the odd "run sphinx multiple times" > approach was because we don't want to ship 'devel' to users, > and as far as I could tell there was no way to have a > single-invocation build of the docs not include it in > eg the index/search (which would then be broken when > we don't install devel/ as part of 'make install'). > Does this patchset result in a set of installed docs > that don't have dangling references ? You are right: * The hidden documents are included in the navigation bar (different from the table of contents). * The search index (which install-doc omits!) includes content from the hidden documents. I have asked on #sphinx-doc. Let's see if there is a solution. It might be possible to hack docs/config.py to exclude devel/ when run from make install-sphinxdocs (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns). This requires building the docs again at install time but the advantage is we get a single searchable set of documentation. Stefan
On Fri, 8 Nov 2019 at 11:39, Stefan Hajnoczi <stefanha@gmail.com> wrote: > > On Fri, Nov 8, 2019 at 11:52 AM Peter Maydell <peter.maydell@linaro.org> wrote: > > So the reason I went for the odd "run sphinx multiple times" > > approach was because we don't want to ship 'devel' to users, > > and as far as I could tell there was no way to have a > > single-invocation build of the docs not include it in > > eg the index/search (which would then be broken when > > we don't install devel/ as part of 'make install'). > > Does this patchset result in a set of installed docs > > that don't have dangling references ? > > You are right: > * The hidden documents are included in the navigation bar (different > from the table of contents). > * The search index (which install-doc omits!) includes content from > the hidden documents. > > I have asked on #sphinx-doc. Let's see if there is a solution. FWIW, this is the thread where I asked on the sphinx-users list about the best way to handle "multiple manuals but we only ship a subset": https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03224.html > It might be possible to hack docs/config.py to exclude devel/ when run > from make install-sphinxdocs > (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns). > This requires building the docs again at install time but the > advantage is we get a single searchable set of documentation. Yeah, if you're willing to build the docs twice (once for local and once for installed) that also works. I'd prefer not to do build work at 'make install' time, though -- if we want to do this we should build them twice at 'make' time and install just the right one. thanks -- PMM
On Fri, 8 Nov 2019 at 11:39, Stefan Hajnoczi <stefanha@gmail.com> wrote: > You are right: > * The hidden documents are included in the navigation bar (different > from the table of contents). > * The search index (which install-doc omits!) includes content from > the hidden documents. What is install-doc failing to install? I just did a test 'make install' into a tempdir, and the search seems to work in that set of installed docs. thanks -- PMM
diff --git a/Makefile b/Makefile index aa9d1a42aa..9487a06bed 100644 --- a/Makefile +++ b/Makefile @@ -815,6 +815,7 @@ endef install-sphinxdocs: sphinxdocs $(call install-manual,interop) $(call install-manual,specs) + $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/index.html" "$(DESTDIR)$(qemu_docdir)/index.html" install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" @@ -1001,7 +1002,7 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak # and handles "don't rebuild things unless necessary" itself. # The '.doctrees' files are cached information to speed this up. .PHONY: sphinxdocs -sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html +sphinxdocs: $(MANUAL_BUILDDIR)/index.html # Canned command to build a single manual # Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man') @@ -1012,14 +1013,8 @@ build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py -$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) - $(call build-manual,devel,html) - -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) - $(call build-manual,interop,html) - -$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) - $(call build-manual,specs,html) +$(MANUAL_BUILDDIR)/index.html: $(call manual-deps,) + $(call build-manual,,html) $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop) $(call build-manual,interop,man) diff --git a/docs/index.rst b/docs/index.rst index baa5791c17..9d6d239561 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,11 +6,36 @@ Welcome to QEMU's documentation! ================================ +.. Non-rst documentation + +`QEMU User Documentation <qemu-doc.html>`_ + +`QEMU QMP Reference Manual <qemu-doc.html>`_ + +`QEMU Guest Agent Protocol Reference <qemu-doc.html>`_ + .. toctree:: :maxdepth: 2 :caption: Contents: interop/index - devel/index specs/index +.. The QEMU Developer's Guide is not included in the main documentation because + users don't need it. +.. toctree:: + :hidden: + + devel/index + +.. Hidden documents that still need to be reviewed and moved to the appropriate + section of the documentation. +.. toctree:: + :hidden: + + arm-cpu-features + cpu-hotplug + microvm + pr-manager + virtio-net-failover + virtio-pmem
Build docs/ in a single sphinx invocation instead of treating docs/{devel,interop,specs} separately. This allows us to build a global index page that links to documentation across the different manuals. Some documentation is built outside of sphinx and is not formatted as reStructuredText. Link directly to the .html files for the time being. If they are converted to .rst files in the future they can be included more elegantly. Sphinx wants to build all .rst files and complains if they are not listed in the table of contents. We have not yet reviewed and categorized some of our .rst files. Hide these files so they are always built (and syntax-checked from now on!) but not visible in the table of contents. Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- Makefile | 13 ++++--------- docs/index.rst | 27 ++++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 10 deletions(-)