Re: [PATCH 1/7] docs: name included files ".rst.inc"

[Peter Maydell]

On Thu, 30 Sept 2021 at 15:51, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Thu, Sep 30, 2021 at 03:47:46PM +0100, Peter Maydell wrote:
> > On Thu, 30 Sept 2021 at 14:33, Paolo Bonzini <pbonzini@redhat.com> wrote:
> > >
> > > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> >
> > > --- a/docs/devel/ci.rst
> > > +++ b/docs/devel/ci.rst
> > > @@ -8,6 +8,6 @@ found at::
> > >
> > >     https://wiki.qemu.org/Testing/CI
> > >
> > > -.. include:: ci-definitions.rst
> > > -.. include:: ci-jobs.rst
> > > -.. include:: ci-runners.rst
> > > +.. include:: ci-definitions.rst.inc
> > > +.. include:: ci-jobs.rst.inc
> > > +.. include:: ci-runners.rst.inc
> >
> > Why are these includes anyway? I think we should either make them
> > proper separate documents (pulled in via a toctree), or just fold
> > the whole thing into a single file if we think it should only be
> > one page. I think it's probably better to reserve the include
> > directive for places where we really do need to textually pull in
> > another file, ie where we have the same text in several documents.
>
> When editting them I find myself getting lost in the rst file. Each
> of them is covering an essentially self-contained topic, so while
> it makes sense for the rendered page to be all one, for editors it
> is nicer for them to be separate.

I think if there's so much text that you get lost when editing it
it's also likely that readers will get lost while reading it.
Mostly I distrust the Sphinx include directive, though...

-- PMM