On Fri, 8 Nov 2019 at 09:59, Stefan Hajnoczi <stefa...@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