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

[Daniel P . Berrangé]

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.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|