linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jonathan Corbet <corbet@lwn.net>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: linux-doc@vger.kernel.org, David Howells <dhowells@redhat.com>
Subject: Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings
Date: Tue, 10 Mar 2020 11:53:28 -0600	[thread overview]
Message-ID: <20200310115328.021999a7@lwn.net> (raw)
In-Reply-To: <637fc605eb2fe6e27d9983ee5c30d78989618313.1583250595.git.mchehab+huawei@kernel.org>

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

  reply	other threads:[~2020-03-10 17:53 UTC|newest]

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-03 15:50 [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format Mauro Carvalho Chehab
2020-03-03 15:50 ` [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings Mauro Carvalho Chehab
2020-03-10 17:53   ` Jonathan Corbet [this message]
2020-03-10 18:29   ` David Howells
2020-03-11 12:11     ` Mauro Carvalho Chehab
2020-03-03 15:50 ` [PATCH 3/9] docs: dmaengine: provider.rst: get rid of some warnings Mauro Carvalho Chehab
2020-03-06 13:39   ` Vinod Koul
2020-03-03 15:50 ` [PATCH 4/9] docs: driver.rst: supress two ReSt warnings Mauro Carvalho Chehab
2020-03-10 17:54   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 5/9] docs: gpio: driver.rst: don't mark literal blocks twice Mauro Carvalho Chehab
2020-03-04 14:20   ` Bartosz Golaszewski
2020-03-03 15:50 ` [PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst Mauro Carvalho Chehab
2020-03-03 17:19   ` Nick Desaulniers
2020-03-04  8:34   ` Federico Vaga
2020-03-10 17:55   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 7/9] docs: filesystems: fuse.rst: supress a Sphinx warning Mauro Carvalho Chehab
2020-03-10 17:55   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 8/9] docs: perf: imx-ddr.rst: get rid of a warning Mauro Carvalho Chehab
2020-03-10 17:56   ` Jonathan Corbet
2020-03-03 15:50 ` [PATCH 9/9] docs: hw-vuln: tsx_async_abort.rst: get rid of an unused ref Mauro Carvalho Chehab
2020-03-10 17:57   ` Jonathan Corbet
2020-03-03 20:42 ` [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format Tom Zanussi
2020-03-03 20:48 ` Steven Rostedt
2020-03-10 17:49   ` Jonathan Corbet

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200310115328.021999a7@lwn.net \
    --to=corbet@lwn.net \
    --cc=dhowells@redhat.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=mchehab+huawei@kernel.org \
    --subject='Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox