Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings

[Jonathan Corbet <corbet@lwn.net>]

On Tue,  3 Mar 2020 16:50:32 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Sphinx doesn't like multi-line literal blocks with ``foobar``:
> 
>     Documentation/watch_queue.rst:109: WARNING: Inline literal start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:186: WARNING: Inline literal start-string without end-string.
>     Documentation/watch_queue.rst:186: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string.
> 
> So, let's use the "::" markup instead.
> 
> While we could do the fix only at the affected lines, let's
> do the same change along the entire file, in order to preserve
> the same look and feel at the entire doc.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

So this doesn't apply to docs-next, of course, since there is no such
file.  Looking in linux-next, I see a few things to comment on beyond
these issues...

 - We *really* don't want to be adding more files like this to the top
   level; we have a directory hierarchy for a reason.  This looks like it
   belongs (mostly) in the core-api manual.

 - Can the user-space example be instead turned into a working program
   under samples (or perhaps a test under tests/)?

The first of these, at least, I would really like to see fixed before this
goes upstream.

Thanks,

jon