On Thu, 30 Sept 2021 at 15:51, Daniel P. Berrangé <[email protected]> wrote: > > On Thu, Sep 30, 2021 at 03:47:46PM +0100, Peter Maydell wrote: > > On Thu, 30 Sept 2021 at 14:33, Paolo Bonzini <[email protected]> wrote: > > > > > > Signed-off-by: Paolo Bonzini <[email protected]> > > > > > --- 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
