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

[Jonathan Corbet <corbet@lwn.net>]

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