On 30/05/19 01:23, Mauro Carvalho Chehab wrote:

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.

Signed-off-by: Mauro Carvalho Chehab mchehab+samsung@kernel.org

Please leave out KVM, I'll fix that instead. Thanks for the report!

Paolo

---

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

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

Am 30.05.19 um 01:23 schrieb Mauro Carvalho Chehab:

This file was renamed, but docs weren't updated accordingly.

WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -function PRIME Buffer Sharing ./drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c' failed with return code 1 WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -internal ./drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c' failed with return code 2

Fixes: 988076cd8c5c ("drm/amdgpu: rename amdgpu_prime.[ch] into amdgpu_dma_buf.[ch]") Signed-off-by: Mauro Carvalho Chehab mchehab+samsung@kernel.org

Reviewed-by: Christian König christian.koenig@amd.com

---

Documentation/gpu/amdgpu.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index a740e491dfcc..a15199b1b02e 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -37,10 +37,10 @@ Buffer Objects PRIME Buffer Sharing

---

-.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :doc: PRIME Buffer Sharing

-.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :internal:

MMU Notifier

Quoting Mauro Carvalho Chehab (2019-05-30 02:23:43)

WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -function Hardware workarounds ./drivers/gpu/drm/i915/intel_workarounds.c' failed with return code 1 WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -function Logical Rings, Logical Ring Contexts and Execlists ./drivers/gpu/drm/i915/intel_lrc.c' failed with return code 1 WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -internal ./drivers/gpu/drm/i915/intel_lrc.c' failed with return code 2

Fixes: 112ed2d31a46 ("drm/i915: Move GraphicsTechnology files under gt/") Signed-off-by: Mauro Carvalho Chehab mchehab+samsung@kernel.org

---

Documentation/gpu/i915.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 055df45596c1..38fefeb99bba 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -61,7 +61,7 @@ Intel GVT-g Host Support(vGPU device model) Workarounds

---

-.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/selftest_workarounds.c

This should be gt/intel_workarounds.c

Do you want me to merge this, or do you plan on merging through documentation tree?

Regards, Joonas