Re: Docs build broken by driver-api/dmaengine/client.rst ? (was Re: [GIT PULL]: dmaengine updates for v5.6-rc1)

[Matthew Wilcox]

On Tue, Jan 28, 2020 at 02:35:17PM +0200, Peter Ujfalusi wrote:
> Hi Michael, Vinod,
> 
> On 28/01/2020 14.24, Vinod Koul wrote:
> > Hi Michael,
> > 
> > On 28-01-20, 22:50, Michael Ellerman wrote:
> >> Hi Vinod,
> >>
> >> Vinod Koul <vkoul@xxxxxxxxxx> writes:
> >>> Hello Linus,
> >>>
> >>> Please pull to receive the dmaengine updates for v5.6-rc1. This time we
> >>> have a bunch of core changes to support dynamic channels, hotplug of
> >>> controllers, new apis for metadata ops etc along with new drivers for
> >>> Intel data accelerators, TI K3 UDMA, PLX DMA engine and hisilicon
> >>> Kunpeng DMA engine. Also usual assorted updates to drivers.
> >>>
> >>> The following changes since commit e42617b825f8073569da76dc4510bfa019b1c35a:
> >>>
> >>>   Linux 5.5-rc1 (2019-12-08 14:57:55 -0800)
> >>>
> >>> are available in the Git repository at:
> >>>
> >>>   git://git.infradead.org/users/vkoul/slave-dma.git tags/dmaengine-5.6-rc1
> >>>
> >>> for you to fetch changes up to 71723a96b8b1367fefc18f60025dae792477d602:
> >>>
> >>>   dmaengine: Create symlinks between DMA channels and slaves (2020-01-24 11:41:32 +0530)
> >>>
> >>> ----------------------------------------------------------------
> >>> dmaengine updates for v5.6-rc1
> >> ...
> >>>
> >>> Peter Ujfalusi (9):
> >>>       dmaengine: doc: Add sections for per descriptor metadata support
> >>
> >> This broke the docs build for me with:
> >>
> >>   Sphinx parallel build error:
> >>   docutils.utils.SystemMessage: /linux/Documentation/driver-api/dmaengine/client.rst:155: (SEVERE/4) Unexpected section title.
> > 
> > Thanks for the report.
> > 
> >>   Optional: per descriptor metadata
> >>   ---------------------------------
> >>
> >>
> >> The patch below fixes the build. It may not produce the output you
> >> intended, it just makes it bold rather than a heading, but it doesn't
> >> really make sense to have a heading inside a numbered list.
> >>
> >> diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst
> >> index a9a7a3c84c63..343df26e73e8 100644
> >> --- a/Documentation/driver-api/dmaengine/client.rst
> >> +++ b/Documentation/driver-api/dmaengine/client.rst
> >> @@ -151,8 +151,8 @@ DMA usage
> >>       Note that callbacks will always be invoked from the DMA
> >>       engines tasklet, never from interrupt context.
> >>  
> >> -  Optional: per descriptor metadata
> >> -  ---------------------------------
> >> +  **Optional: per descriptor metadata**
> >> +
> > 
> > I have modified this to below as this:
> > 
> > --- a/Documentation/driver-api/dmaengine/client.rst
> > +++ b/Documentation/driver-api/dmaengine/client.rst
> > @@ -151,8 +151,8 @@ The details of these operations are:
> >       Note that callbacks will always be invoked from the DMA
> >       engines tasklet, never from interrupt context.
> >  
> > -  Optional: per descriptor metadata
> > -  ---------------------------------
> > +Optional: per descriptor metadata
> > +---------------------------------
> >    DMAengine provides two ways for metadata support.
> >  
> >    DESC_METADATA_CLIENT
> > 
> > And I will add this as fixes and it should be in linux-next tomorrow
> 
> Sorry for breaking the build and thanks Vinod for the quick fix!

Can I suggest, in future, 'make W=1'.  That will run the kernel-doc
script which would presumably have caught this problem.  If we get all
the existing doc errors cleaned up, we can promote that to be run as
part of the standard build, but until then we don't want to dump 700
new errors on everybody.