| Message ID | 20210930133250.181156-2-pbonzini@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | Cleanup sectioning in a few doc files | expand |
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
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 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
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
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
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%)