LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To: Christophe Leroy <christophe.leroy@c-s.fr>
Cc: "Linux Doc Mailing List" <linux-doc@vger.kernel.org>,
	kvm@vger.kernel.org, "Radim Krčmář" <rkrcmar@redhat.com>,
	"Maxime Ripard" <maxime.ripard@bootlin.com>,
	dri-devel@lists.freedesktop.org,
	platform-driver-x86@vger.kernel.org,
	"Paul Mackerras" <paulus@samba.org>,
	linux-stm32@st-md-mailman.stormreply.com,
	"Alexandre Torgue" <alexandre.torgue@st.com>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"David Airlie" <airlied@linux.ie>,
	"Andrew Donnellan" <ajd@linux.ibm.com>,
	linux-pm@vger.kernel.org,
	"Maarten Lankhorst" <maarten.lankhorst@linux.intel.com>,
	"Matan Ziv-Av" <matan@svgalib.org>,
	"Mauro Carvalho Chehab" <mchehab@infradead.org>,
	"Daniel Vetter" <daniel@ffwll.ch>, "Sean Paul" <sean@poorly.run>,
	linux-arm-kernel@lists.infradead.org,
	linux-kernel@vger.kernel.org,
	"Maxime Coquelin" <mcoquelin.stm32@gmail.com>,
	"Frederic Barrat" <fbarrat@linux.ibm.com>,
	"Paolo Bonzini" <pbonzini@redhat.com>,
	linuxppc-dev@lists.ozlabs.org,
	"Georgi Djakov" <georgi.djakov@linaro.org>
Subject: Re: [PATCH 09/22] docs: mark orphan documents as such
Date: Tue, 4 Jun 2019 07:10:48 -0300	[thread overview]
Message-ID: <20190604071048.4f226fff@coco.lan> (raw)
In-Reply-To: <2891a08c-50b1-db33-0e96-740d45c5235f@c-s.fr>

Em Mon, 3 Jun 2019 09:32:54 +0200
Christophe Leroy <christophe.leroy@c-s.fr> escreveu:

> Le 30/05/2019 à 01:23, Mauro Carvalho Chehab a écrit :
> > Sphinx doesn't like orphan documents:
> > 
> >      Documentation/accelerators/ocxl.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/stm32f429-overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/stm32f746-overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/stm32f769-overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/stm32h743-overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/arm/stm32/stm32mp157-overview.rst: WARNING: document isn't included in any toctree
> >      Documentation/gpu/msm-crash-dump.rst: WARNING: document isn't included in any toctree
> >      Documentation/interconnect/interconnect.rst: WARNING: document isn't included in any toctree
> >      Documentation/laptops/lg-laptop.rst: WARNING: document isn't included in any toctree
> >      Documentation/powerpc/isa-versions.rst: WARNING: document isn't included in any toctree
> >      Documentation/virtual/kvm/amd-memory-encryption.rst: WARNING: document isn't included in any toctree
> >      Documentation/virtual/kvm/vcpu-requests.rst: WARNING: document isn't included in any toctree
> > 
> > So, while they aren't on any toctree, add :orphan: to them, in order
> > to silent this warning.  
> 
> Are those files really not meant to be included in a toctree ?
> 
> Shouldn't we include them in the relevant toctree instead of just 
> shutting up Sphinx warnings ?

This is a good point. My understanding is that those orphaned docs
are there for two reasons:

1) someone created a new document as .rst but there's no index.rst file yet,
as there are lots of other documents already there not converted. That's
the case, for example, of the ones under Documentation/arm;

2) They're part of an undergoing effort of converting stuff to ReST.
One opted to keep it orphaned temporarily in order to avoid merge
conflicts.

That's said, I have myself a big (/86 patches and growing) series
with do a huge step on txt->rst conversion (it covers a significant
amount of documentation). On this series, I'm removing the orphaned
tags for several files (including, for example, those at Documentation/arm).

Yet, it is a lot easier to see if such series is not introducing
warnings regressions if we first address those.

It should be notice that discovering the orphaned files should be as
simple as:

	git grep -l ":orphan:" Documentation

> 
> Christophe
> 
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >   Documentation/accelerators/ocxl.rst                 | 2 ++
> >   Documentation/arm/stm32/overview.rst                | 2 ++
> >   Documentation/arm/stm32/stm32f429-overview.rst      | 2 ++
> >   Documentation/arm/stm32/stm32f746-overview.rst      | 2 ++
> >   Documentation/arm/stm32/stm32f769-overview.rst      | 2 ++
> >   Documentation/arm/stm32/stm32h743-overview.rst      | 2 ++
> >   Documentation/arm/stm32/stm32mp157-overview.rst     | 2 ++
> >   Documentation/gpu/msm-crash-dump.rst                | 2 ++
> >   Documentation/interconnect/interconnect.rst         | 2 ++
> >   Documentation/laptops/lg-laptop.rst                 | 2 ++
> >   Documentation/powerpc/isa-versions.rst              | 2 ++
> >   Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
> >   Documentation/virtual/kvm/vcpu-requests.rst         | 2 ++
> >   13 files changed, 26 insertions(+)
> > 
> > diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst
> > index 14cefc020e2d..b1cea19a90f5 100644
> > --- a/Documentation/accelerators/ocxl.rst
> > +++ b/Documentation/accelerators/ocxl.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   ========================================================
> >   OpenCAPI (Open Coherent Accelerator Processor Interface)
> >   ========================================================
> > diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arm/stm32/overview.rst
> > index 85cfc8410798..f7e734153860 100644
> > --- a/Documentation/arm/stm32/overview.rst
> > +++ b/Documentation/arm/stm32/overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   ========================
> >   STM32 ARM Linux Overview
> >   ========================
> > diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst
> > index 18feda97f483..65bbb1c3b423 100644
> > --- a/Documentation/arm/stm32/stm32f429-overview.rst
> > +++ b/Documentation/arm/stm32/stm32f429-overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   STM32F429 Overview
> >   ==================
> >   
> > diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst
> > index b5f4b6ce7656..42d593085015 100644
> > --- a/Documentation/arm/stm32/stm32f746-overview.rst
> > +++ b/Documentation/arm/stm32/stm32f746-overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   STM32F746 Overview
> >   ==================
> >   
> > diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst
> > index 228656ced2fe..f6adac862b17 100644
> > --- a/Documentation/arm/stm32/stm32f769-overview.rst
> > +++ b/Documentation/arm/stm32/stm32f769-overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   STM32F769 Overview
> >   ==================
> >   
> > diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst
> > index 3458dc00095d..c525835e7473 100644
> > --- a/Documentation/arm/stm32/stm32h743-overview.rst
> > +++ b/Documentation/arm/stm32/stm32h743-overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   STM32H743 Overview
> >   ==================
> >   
> > diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst
> > index 62e176d47ca7..2c52cd020601 100644
> > --- a/Documentation/arm/stm32/stm32mp157-overview.rst
> > +++ b/Documentation/arm/stm32/stm32mp157-overview.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   STM32MP157 Overview
> >   ===================
> >   
> > diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst
> > index 757cd257e0d8..240ef200f76c 100644
> > --- a/Documentation/gpu/msm-crash-dump.rst
> > +++ b/Documentation/gpu/msm-crash-dump.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   =====================
> >   MSM Crash Dump Format
> >   =====================
> > diff --git a/Documentation/interconnect/interconnect.rst b/Documentation/interconnect/interconnect.rst
> > index c3e004893796..56e331dab70e 100644
> > --- a/Documentation/interconnect/interconnect.rst
> > +++ b/Documentation/interconnect/interconnect.rst
> > @@ -1,5 +1,7 @@
> >   .. SPDX-License-Identifier: GPL-2.0
> >   
> > +:orphan:
> > +
> >   =====================================
> >   GENERIC SYSTEM INTERCONNECT SUBSYSTEM
> >   =====================================
> > diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
> > index aa503ee9b3bc..f2c2ffe31101 100644
> > --- a/Documentation/laptops/lg-laptop.rst
> > +++ b/Documentation/laptops/lg-laptop.rst
> > @@ -1,5 +1,7 @@
> >   .. SPDX-License-Identifier: GPL-2.0+
> >   
> > +:orphan:
> > +
> >   LG Gram laptop extra features
> >   =============================
> >   
> > diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
> > index 812e20cc898c..66c24140ebf1 100644
> > --- a/Documentation/powerpc/isa-versions.rst
> > +++ b/Documentation/powerpc/isa-versions.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   CPU to ISA Version Mapping
> >   ==========================
> >   
> > diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst
> > index 659bbc093b52..33d697ab8a58 100644
> > --- a/Documentation/virtual/kvm/amd-memory-encryption.rst
> > +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   ======================================
> >   Secure Encrypted Virtualization (SEV)
> >   ======================================
> > diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst
> > index 5feb3706a7ae..c1807a1b92e6 100644
> > --- a/Documentation/virtual/kvm/vcpu-requests.rst
> > +++ b/Documentation/virtual/kvm/vcpu-requests.rst
> > @@ -1,3 +1,5 @@
> > +:orphan:
> > +
> >   =================
> >   KVM VCPU Requests
> >   =================
> >   



Thanks,
Mauro

  reply	other threads:[~2019-06-04 10:11 UTC|newest]

Thread overview: 44+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-29 23:23 [PATCH 00/22] Some documentation fixes Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 01/22] ABI: sysfs-devices-system-cpu: point to the right docs Mauro Carvalho Chehab
2019-05-30 16:57   ` Rafael J. Wysocki
2019-05-29 23:23 ` [PATCH 02/22] isdn: mISDN: remove a bogus reference to a non-existing doc Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 03/22] dt: fix broken references to nand.txt Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 04/22] docs: zh_CN: get rid of basic_profiling.txt Mauro Carvalho Chehab
2019-06-02 14:36   ` Alex Shi
2019-05-29 23:23 ` [PATCH 05/22] mfd: madera: Fix bad reference to pinctrl.txt file Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 06/22] doc: it_IT: fix reference to magic-number.rst Mauro Carvalho Chehab
2019-05-30 20:15   ` Federico Vaga
2019-05-29 23:23 ` [PATCH 07/22] docs: mm: numaperf.rst: get rid of a build warning Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 08/22] docs: bpf: get rid of two warnings Mauro Carvalho Chehab
2019-05-30 18:08   ` Song Liu
2019-05-29 23:23 ` [PATCH 09/22] docs: mark orphan documents as such Mauro Carvalho Chehab
2019-05-30  8:30   ` Paolo Bonzini
2019-06-03  7:32   ` Christophe Leroy
2019-06-04 10:10     ` Mauro Carvalho Chehab [this message]
2019-05-29 23:23 ` [PATCH 10/22] docs: amd-memory-encryption.rst get rid of warnings Mauro Carvalho Chehab
2019-05-30  8:30   ` Paolo Bonzini
2019-05-29 23:23 ` [PATCH 11/22] gpu: amdgpu: fix broken amdgpu_dma_buf.c references Mauro Carvalho Chehab
2019-05-31 14:00   ` Christian König
2019-05-31 15:03     ` Alex Deucher
2019-05-29 23:23 ` [PATCH 12/22] gpu: i915.rst: Fix references to renamed files Mauro Carvalho Chehab
2019-05-31  7:40   ` Jani Nikula
2019-05-31  9:02   ` Joonas Lahtinen
2019-05-29 23:23 ` [PATCH 13/22] docs: zh_CN: avoid duplicate citation references Mauro Carvalho Chehab
2019-06-02 15:01   ` Alex Shi
2019-06-04 10:20     ` Mauro Carvalho Chehab
2019-06-04 10:43       ` Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 14/22] docs: vm: hmm.rst: fix some warnings Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 15/22] docs: it: license-rules.rst: get rid of warnings Mauro Carvalho Chehab
2019-05-30 20:23   ` Federico Vaga
2019-05-29 23:23 ` [PATCH 16/22] docs: gpio: driver.rst: fix a bad tag Mauro Carvalho Chehab
2019-06-07 20:57   ` Linus Walleij
2019-05-29 23:23 ` [PATCH 17/22] docs: soundwire: locking: fix tags for a code-block Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 18/22] docs: security: trusted-encrypted.rst: fix code-block tag Mauro Carvalho Chehab
2019-05-30 19:43   ` James Morris
2019-06-03 20:29   ` Jarkko Sakkinen
2019-05-29 23:23 ` [PATCH 19/22] docs: security: core.rst: Fix several warnings Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 20/22] docs: net: dpio-driver.rst: fix two codeblock warnings Mauro Carvalho Chehab
2019-05-29 23:23 ` [PATCH 21/22] docs: net: sja1105.rst: fix table format Mauro Carvalho Chehab
2019-05-29 23:26   ` Vladimir Oltean
     [not found] ` <f9fecacbe4ce0b2b3aed38d71ae3753f2daf3ce3.1559171394.git.mchehab+samsung@kernel.org>
2019-05-30 13:12   ` [PATCH 22/22] docs: fix broken documentation links Sven Van Asbroeck
     [not found]   ` <1574052.9PXfBvmXpz@harkonnen>
2019-05-30 22:49     ` Michael S. Tsirkin

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190604071048.4f226fff@coco.lan \
    --to=mchehab+samsung@kernel.org \
    --cc=airlied@linux.ie \
    --cc=ajd@linux.ibm.com \
    --cc=alexandre.torgue@st.com \
    --cc=christophe.leroy@c-s.fr \
    --cc=corbet@lwn.net \
    --cc=daniel@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=fbarrat@linux.ibm.com \
    --cc=georgi.djakov@linaro.org \
    --cc=kvm@vger.kernel.org \
    --cc=linux-arm-kernel@lists.infradead.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-pm@vger.kernel.org \
    --cc=linux-stm32@st-md-mailman.stormreply.com \
    --cc=linuxppc-dev@lists.ozlabs.org \
    --cc=maarten.lankhorst@linux.intel.com \
    --cc=matan@svgalib.org \
    --cc=maxime.ripard@bootlin.com \
    --cc=mchehab@infradead.org \
    --cc=mcoquelin.stm32@gmail.com \
    --cc=paulus@samba.org \
    --cc=pbonzini@redhat.com \
    --cc=platform-driver-x86@vger.kernel.org \
    --cc=rkrcmar@redhat.com \
    --cc=sean@poorly.run \
    --subject='Re: [PATCH 09/22] docs: mark orphan documents as such' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).