On Fri, Nov 8, 2019 at 11:52 AM Peter Maydell <peter.mayd...@linaro.org> wrote:
> 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 ?
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
