[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/7] docs: name included files ".rst.inc"
From: |
Daniel P . Berrangé |
Subject: |
Re: [PATCH 1/7] docs: name included files ".rst.inc" |
Date: |
Thu, 30 Sep 2021 15:51:44 +0100 |
User-agent: |
Mutt/2.0.7 (2021-05-04) |
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 :|