Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/devel/{ci-definitions.rst => ci-definitions.rst.inc} | 0
 docs/devel/{ci-jobs.rst => ci-jobs.rst.inc}               | 0
 docs/devel/{ci-runners.rst => ci-runners.rst.inc}         | 0
 docs/devel/ci.rst                                         | 6 +++---
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename docs/devel/{ci-definitions.rst => ci-definitions.rst.inc} (100%)
 rename docs/devel/{ci-jobs.rst => ci-jobs.rst.inc} (100%)
 rename docs/devel/{ci-runners.rst => ci-runners.rst.inc} (100%)

diff --git a/docs/devel/ci-definitions.rst b/docs/devel/ci-definitions.rst.inc
similarity index 100%
rename from docs/devel/ci-definitions.rst
rename to docs/devel/ci-definitions.rst.inc
diff --git a/docs/devel/ci-jobs.rst b/docs/devel/ci-jobs.rst.inc
similarity index 100%
rename from docs/devel/ci-jobs.rst
rename to docs/devel/ci-jobs.rst.inc
diff --git a/docs/devel/ci-runners.rst b/docs/devel/ci-runners.rst.inc
similarity index 100%
rename from docs/devel/ci-runners.rst
rename to docs/devel/ci-runners.rst.inc
diff --git a/docs/devel/ci.rst b/docs/devel/ci.rst
index 8d95247188..d106610096 100644
--- 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
-- 
2.31.1

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.

thanks
-- PMM

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 :|

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

Emacs recognizes .rst, but doesn't recognize .rst.inc.  Sure we want
file names that defeat common tooling?

On 01/10/21 07:14, Markus Armbruster wrote:
> Emacs recognizes .rst, but doesn't recognize .rst.inc.  Sure we want
> file names that defeat common tooling?
> 
> 

I don't do Emacs, but a patch for .editorconfig should rectify that.

Paolo

On Fri, 1 Oct 2021 at 06:15, Markus Armbruster <armbru@redhat.com> wrote:
>
> Emacs recognizes .rst, but doesn't recognize .rst.inc.  Sure we want
> file names that defeat common tooling?

*.rst.inc is the standard convention we have for included
rst file fragments: we already use it for 9 files in docs/.

It also matches with the use of '.c.inc' for included C files
that we use elsewhere. (In that case we are constrained by
Meson, which will not permit us to use '.inc.c'.)

-- PMM