[PATCH] doc: fix warnings for unused files in toctree

[PATCH] doc: fix warnings for unused files in toctree

[Héctor Orón Martínez]

[-- Attachment #1: Type: text/plain, Size: 215 bytes --]

Hello,

  Find patch attached to fix some warnings about unused files in
toctree and unexistent files, listed in toctrees.

Regards
-- 
 Héctor Orón  -.. . -... .. .- -.   -.. . ...- . .-.. --- .--. . .-.

[-- Attachment #2: 0001-doc-fix-warnings-for-unused-files-in-toctree.patch --]
[-- Type: text/x-patch, Size: 2848 bytes --]

From 9cf03380336183ead665611b61f4a36c01c4dc77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A9ctor=20Or=C3=B3n=20Mart=C3=ADnez?=
 <hector.oron@gmail.com>
Date: Mon, 28 Oct 2019 17:49:21 +0100
Subject: [PATCH] doc: fix warnings for unused files in toctree
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There are a bunch of warnings for missing files in the toctree,
and there are files that have been removed.

The following change fix those warnings.

Signed-off-by: Héctor Orón Martínez <hector.oron@gmail.com>
---
 Documentation/admin-guide/device-mapper/index.rst | 1 +
 Documentation/admin-guide/perf/index.rst          | 1 +
 Documentation/misc-devices/index.rst              | 1 -
 Documentation/usb/index.rst                       | 2 --
 Documentation/usb/text_files.rst                  | 6 ------
 5 files changed, 2 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
index c77c58b8f67b..3ff568d60759 100644
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -19,6 +19,7 @@ Device Mapper
     dm-service-time
     dm-uevent
     dm-zoned
+    dm-clone
     era
     kcopyd
     linear
diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst
index ee4bfd2a740f..0f450a1f64c8 100644
--- a/Documentation/admin-guide/perf/index.rst
+++ b/Documentation/admin-guide/perf/index.rst
@@ -14,3 +14,4 @@ Performance monitor support
    xgene-pmu
    arm_dsu_pmu
    thunderx2-pmu
+   imx-ddr
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index f11c5daeada5..a57f92dfe49a 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -20,4 +20,3 @@ fit into other categories.
    isl29003
    lis3lv02d
    max6875
-   xilinx_sdfec
diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
index e55386a4abfb..36b6ebd9a9d9 100644
--- a/Documentation/usb/index.rst
+++ b/Documentation/usb/index.rst
@@ -22,11 +22,9 @@ USB support
     misc_usbsevseg
     mtouchusb
     ohci
-    rio
     usbip_protocol
     usbmon
     usb-serial
-    wusb-design-overview
 
     usb-help
     text_files
diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst
index 6a8d3fcf64b6..1c18c05c3920 100644
--- a/Documentation/usb/text_files.rst
+++ b/Documentation/usb/text_files.rst
@@ -16,12 +16,6 @@ USB devfs drop permissions source
 .. literalinclude:: usbdevfs-drop-permissions.c
     :language: c
 
-WUSB command line script to manipulate auth credentials
--------------------------------------------------------
-
-.. literalinclude:: wusb-cbaf
-   :language: shell
-
 Credits
 -------
 
-- 
2.20.1

Re: [PATCH] doc: fix warnings for unused files in toctree

[Héctor Orón Martínez]

[-- Attachment #1: Type: text/plain, Size: 600 bytes --]

Hello,

  I was planning to add more fixes in separated commit, but while
working on it, apparently it could be part of the previous commit.
  Apologies, find updated patch.

Missatge de Héctor Orón Martínez <hector.oron@gmail.com> del dia dl.,
28 d’oct. 2019 a les 18:12:
>
> Hello,
>
>   Find patch attached to fix some warnings about unused files in
> toctree and unexistent files, listed in toctrees.
>
> Regards
> --
>  Héctor Orón  -.. . -... .. .- -.   -.. . ...- . .-.. --- .--. . .-.



-- 
 Héctor Orón  -.. . -... .. .- -.   -.. . ...- . .-.. --- .--. . .-.

[-- Attachment #2: 0001-doc-fix-warnings-for-unused-files-in-toctree.patch --]
[-- Type: text/x-patch, Size: 4567 bytes --]

From 4c10f2574fe10fd197491d24a6494843eb136c93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A9ctor=20Or=C3=B3n=20Mart=C3=ADnez?=
 <hector.oron@gmail.com>
Date: Mon, 28 Oct 2019 17:49:21 +0100
Subject: [PATCH] doc: fix warnings for unused files in toctree
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There are a bunch of warnings for missing files in the toctree,
and there are files that have been removed.

The following change fix those warnings.

Signed-off-by: Héctor Orón Martínez <hector.oron@gmail.com>
---
 Documentation/admin-guide/device-mapper/index.rst |  1 +
 Documentation/admin-guide/perf/index.rst          |  1 +
 Documentation/driver-api/dma-buf.rst              | 12 ------------
 Documentation/driver-api/index.rst                |  1 -
 Documentation/gpu/i915.rst                        |  9 ---------
 Documentation/misc-devices/index.rst              |  1 -
 Documentation/usb/index.rst                       |  2 --
 Documentation/usb/text_files.rst                  |  6 ------
 8 files changed, 2 insertions(+), 31 deletions(-)

diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
index c77c58b8f67b..3ff568d60759 100644
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -19,6 +19,7 @@ Device Mapper
     dm-service-time
     dm-uevent
     dm-zoned
+    dm-clone
     era
     kcopyd
     linear
diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst
index ee4bfd2a740f..0f450a1f64c8 100644
--- a/Documentation/admin-guide/perf/index.rst
+++ b/Documentation/admin-guide/perf/index.rst
@@ -14,3 +14,4 @@ Performance monitor support
    xgene-pmu
    arm_dsu_pmu
    thunderx2-pmu
+   imx-ddr
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index b541e97c7ab1..d2f3c95ea9ed 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -115,18 +115,6 @@ Kernel Functions and Structures Reference
 .. kernel-doc:: include/linux/dma-buf.h
    :internal:
 
-Reservation Objects
--------------------
-
-.. kernel-doc:: drivers/dma-buf/reservation.c
-   :doc: Reservation Object Overview
-
-.. kernel-doc:: drivers/dma-buf/reservation.c
-   :export:
-
-.. kernel-doc:: include/linux/reservation.h
-   :internal:
-
 DMA Fences
 ----------
 
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 38e638abe3eb..6d46ceeb62c4 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -93,7 +93,6 @@ available subsections can be seen below.
    pwm
    rfkill
    serial/index
-   sgi-ioc4
    sm501
    smsc_ece1099
    switchtec
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 3415255ad3dc..7d1f65612856 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -358,15 +358,6 @@ Batchbuffer Parsing
 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
    :internal:
 
-Batchbuffer Pools
------------------
-
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
-   :doc: batch pool
-
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
-   :internal:
-
 User Batchbuffer Execution
 --------------------------
 
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index f11c5daeada5..a57f92dfe49a 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -20,4 +20,3 @@ fit into other categories.
    isl29003
    lis3lv02d
    max6875
-   xilinx_sdfec
diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
index e55386a4abfb..36b6ebd9a9d9 100644
--- a/Documentation/usb/index.rst
+++ b/Documentation/usb/index.rst
@@ -22,11 +22,9 @@ USB support
     misc_usbsevseg
     mtouchusb
     ohci
-    rio
     usbip_protocol
     usbmon
     usb-serial
-    wusb-design-overview
 
     usb-help
     text_files
diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst
index 6a8d3fcf64b6..1c18c05c3920 100644
--- a/Documentation/usb/text_files.rst
+++ b/Documentation/usb/text_files.rst
@@ -16,12 +16,6 @@ USB devfs drop permissions source
 .. literalinclude:: usbdevfs-drop-permissions.c
     :language: c
 
-WUSB command line script to manipulate auth credentials
--------------------------------------------------------
-
-.. literalinclude:: wusb-cbaf
-   :language: shell
-
 Credits
 -------
 
-- 
2.20.1

Re: [PATCH] doc: fix warnings for unused files in toctree

[Jonathan Corbet]

On Mon, 28 Oct 2019 18:26:09 +0100
Héctor Orón Martínez <hector.oron@gmail.com> wrote:

>   I was planning to add more fixes in separated commit, but while
> working on it, apparently it could be part of the previous commit.
>   Apologies, find updated patch.

Thanks for working to improve the documentation!  I do have a couple of
requests, though...

 - Please send patches inline, rather than as attachments; that makes
   them much easier to review.

 - Please work against docs-next and look at the history of what you are
   working on. For example:

> diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
> index b541e97c7ab1..d2f3c95ea9ed 100644
> --- a/Documentation/driver-api/dma-buf.rst
> +++ b/Documentation/driver-api/dma-buf.rst
> @@ -115,18 +115,6 @@ Kernel Functions and Structures Reference
>  .. kernel-doc:: include/linux/dma-buf.h
>     :internal:
>  
> -Reservation Objects
> --------------------
> -
> -.. kernel-doc:: drivers/dma-buf/reservation.c
> -   :doc: Reservation Object Overview
> -
> -.. kernel-doc:: drivers/dma-buf/reservation.c
> -   :export:
> -
> -.. kernel-doc:: include/linux/reservation.h
> -   :internal:

This is not a correct fix; those files have been renamed, not removed.
There is a (correct) fix in docs-next, and has been for some weeks now.

If you could please review the rest of your patch and resubmit against
docs-next, I would appreciate it.

Many thanks,

jon

Re: [PATCH] doc: fix warnings for unused files in toctree

[Héctor Orón Martínez]

Hello Jonathan,

Missatge de Jonathan Corbet <corbet@lwn.net> del dia dt., 29 d’oct.
2019 a les 10:21:

>  - Please send patches inline, rather than as attachments; that makes
>    them much easier to review.

Sure, I need to fix my SMTP git configuration.

>  - Please work against docs-next and look at the history of what you are
>    working on. For example:

Where do I find the docs-next tree?

> If you could please review the rest of your patch and resubmit against
> docs-next, I would appreciate it.

I will do. Thanks for your review and hints!

Regards,
-- 
 Héctor Orón  -.. . -... .. .- -.   -.. . ...- . .-.. --- .--. . .-.

Re: [PATCH] doc: fix warnings for unused files in toctree

[Jonathan Corbet]

On Tue, 29 Oct 2019 11:58:21 +0100
Héctor Orón Martínez <hector.oron@gmail.com> wrote:

> >  - Please work against docs-next and look at the history of what you are
> >    working on. For example:  
> 
> Where do I find the docs-next tree?

It's in the MAINTAINERS file:

T:	git git://git.lwn.net/linux.git docs-next

Thanks,

jon

[PATCH] doc: fix warnings for unused files in toctree

[hector.oron]

From: Héctor Orón Martínez <hector.oron@gmail.com>

There are a bunch of warnings for missing files in the toctree,
and there are files that have been removed.

The following change fix those warnings.

Signed-off-by: Héctor Orón Martínez <hector.oron@gmail.com>
---
 Documentation/admin-guide/device-mapper/index.rst | 1 +
 Documentation/admin-guide/perf/index.rst          | 1 +
 Documentation/gpu/i915.rst                        | 9 ---------
 Documentation/misc-devices/index.rst              | 1 -
 Documentation/usb/index.rst                       | 2 --
 Documentation/usb/text_files.rst                  | 6 ------
 6 files changed, 2 insertions(+), 18 deletions(-)

diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
index 4872fb6d2952..2545e4eaf6e5 100644
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -20,6 +20,7 @@ Device Mapper
     dm-service-time
     dm-uevent
     dm-zoned
+    dm-clone
     era
     kcopyd
     linear
diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst
index 47c99f40cc16..0795994865e0 100644
--- a/Documentation/admin-guide/perf/index.rst
+++ b/Documentation/admin-guide/perf/index.rst
@@ -15,3 +15,4 @@ Performance monitor support
    xgene-pmu
    arm_dsu_pmu
    thunderx2-pmu
+   imx-ddr
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 3415255ad3dc..7d1f65612856 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -358,15 +358,6 @@ Batchbuffer Parsing
 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
    :internal:
 
-Batchbuffer Pools
------------------
-
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
-   :doc: batch pool
-
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
-   :internal:
-
 User Batchbuffer Execution
 --------------------------
 
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index f11c5daeada5..a57f92dfe49a 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -20,4 +20,3 @@ fit into other categories.
    isl29003
    lis3lv02d
    max6875
-   xilinx_sdfec
diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
index e55386a4abfb..36b6ebd9a9d9 100644
--- a/Documentation/usb/index.rst
+++ b/Documentation/usb/index.rst
@@ -22,11 +22,9 @@ USB support
     misc_usbsevseg
     mtouchusb
     ohci
-    rio
     usbip_protocol
     usbmon
     usb-serial
-    wusb-design-overview
 
     usb-help
     text_files
diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst
index 6a8d3fcf64b6..1c18c05c3920 100644
--- a/Documentation/usb/text_files.rst
+++ b/Documentation/usb/text_files.rst
@@ -16,12 +16,6 @@ USB devfs drop permissions source
 .. literalinclude:: usbdevfs-drop-permissions.c
     :language: c
 
-WUSB command line script to manipulate auth credentials
--------------------------------------------------------
-
-.. literalinclude:: wusb-cbaf
-   :language: shell
-
 Credits
 -------
 
-- 
2.20.1

Re: [PATCH] doc: fix warnings for unused files in toctree

[Jonathan Corbet]

On Tue, 29 Oct 2019 14:44:45 +0100
hector.oron@gmail.com wrote:

> From: Héctor Orón Martínez <hector.oron@gmail.com>
> 
> There are a bunch of warnings for missing files in the toctree,
> and there are files that have been removed.
> 
> The following change fix those warnings.
> 
> Signed-off-by: Héctor Orón Martínez <hector.oron@gmail.com>
> ---
>  Documentation/admin-guide/device-mapper/index.rst | 1 +
>  Documentation/admin-guide/perf/index.rst          | 1 +
>  Documentation/gpu/i915.rst                        | 9 ---------
>  Documentation/misc-devices/index.rst              | 1 -
>  Documentation/usb/index.rst                       | 2 --
>  Documentation/usb/text_files.rst                  | 6 ------
>  6 files changed, 2 insertions(+), 18 deletions(-)

OK, we're getting closer, but there are still some learning opportunites
here...:)  The first of these is that it would be best to split these into
independent patches so that they can be considered separately; we'll see
why.

> diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
> index 4872fb6d2952..2545e4eaf6e5 100644
> --- a/Documentation/admin-guide/device-mapper/index.rst
> +++ b/Documentation/admin-guide/device-mapper/index.rst
> @@ -20,6 +20,7 @@ Device Mapper
>      dm-service-time
>      dm-uevent
>      dm-zoned
> +    dm-clone
>      era
>      kcopyd
>      linear

This one is good.

> diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst
> index 47c99f40cc16..0795994865e0 100644
> --- a/Documentation/admin-guide/perf/index.rst
> +++ b/Documentation/admin-guide/perf/index.rst
> @@ -15,3 +15,4 @@ Performance monitor support
>     xgene-pmu
>     arm_dsu_pmu
>     thunderx2-pmu
> +   imx-ddr

This one is already fixed in docs-next.

> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 3415255ad3dc..7d1f65612856 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -358,15 +358,6 @@ Batchbuffer Parsing
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
>     :internal:
>  
> -Batchbuffer Pools
> ------------------
> -
> -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
> -   :doc: batch pool
> -
> -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
> -   :internal:
> -
>  User Batchbuffer Execution
>  --------------------------

This one, instead, is fixed in the DRM tree; you would have seen that had
you looked in linux-next.  That's one of the challenges of the docs
"subsystem" - it gets touched from all over.

> diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
> index f11c5daeada5..a57f92dfe49a 100644
> --- a/Documentation/misc-devices/index.rst
> +++ b/Documentation/misc-devices/index.rst
> @@ -20,4 +20,3 @@ fit into other categories.
>     isl29003
>     lis3lv02d
>     max6875
> -   xilinx_sdfec

The correct fix here was to add the missing document; that was done in
docs-next a couple of weeks or so ago.

> diff --git a/Documentation/usb/index.rst b/Documentation/usb/index.rst
> index e55386a4abfb..36b6ebd9a9d9 100644
> --- a/Documentation/usb/index.rst
> +++ b/Documentation/usb/index.rst
> @@ -22,11 +22,9 @@ USB support
>      misc_usbsevseg
>      mtouchusb
>      ohci
> -    rio
>      usbip_protocol
>      usbmon
>      usb-serial
> -    wusb-design-overview
>  
>      usb-help
>      text_files

This one seems good.  But it's always worth doing a bit of digging to
figure out how something came to be...in this case, the rio driver was
deleted and wusbcore went into staging:

	015664d15270 USB: rio500: Remove Rio 500 kernel driver
	71ed79b0e4be USB: Move wusbcore and UWB to staging as it is obsolete

Submitting those separately with Fixes: tags would be good.

> diff --git a/Documentation/usb/text_files.rst b/Documentation/usb/text_files.rst
> index 6a8d3fcf64b6..1c18c05c3920 100644
> --- a/Documentation/usb/text_files.rst
> +++ b/Documentation/usb/text_files.rst
> @@ -16,12 +16,6 @@ USB devfs drop permissions source
>  .. literalinclude:: usbdevfs-drop-permissions.c
>      :language: c
>  
> -WUSB command line script to manipulate auth credentials
> --------------------------------------------------------
> -
> -.. literalinclude:: wusb-cbaf
> -   :language: shell
> -
>  Credits
>  -------

This goes with the wusb change as well.

I do appreciate your working to make the documentation better, sorry it can
be so painful to get started...

Thanks,

jon