Re: [PATCH 2/3] docs: build a global index page

[Stefan Hajnoczi]

On Fri, Nov 8, 2019 at 11:52 AM Peter Maydell <address@hidden> wrote:
> On Fri, 8 Nov 2019 at 09:59, Stefan Hajnoczi <address@hidden> 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