Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1735939 > unrolled thread

Re: [RFC PATCH v4 3/6] i2c: add docs to clarify DMA handling

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [RFC PATCH v4 3/6] i2c: add docs to clarify DMA handling Wolfram Sang <wsa@the-dreams.de> - 2017-09-20 19:20 +0200
    Re: [RFC PATCH v4 3/6] i2c: add docs to clarify DMA handling Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-09-20 20:30 +0200
      Re: [RFC PATCH v4 3/6] i2c: add docs to clarify DMA handling Wolfram Sang <wsa@the-dreams.de> - 2017-09-20 20:50 +0200

#1735939 — Re: [RFC PATCH v4 3/6] i2c: add docs to clarify DMA handling

[Multipart message — attachments visible in raw view] — view raw

Hi Mauro,

> > +Linux I2C and DMA
> > +-----------------
> 
> I would use, instead:
> 
> =================
> Linux I2C and DMA
> =================
> 
> As this is the way we're starting document titles, after converted to
> ReST. So, better to have it already using the right format, as one day

I did this.

> There are also a couple of things here that Sphinx would complain.

The only complaint I got was

	WARNING: document isn't included in any toctree

which makes sense because I renamed it only temporarily to *.rst

> So, it could be worth to rename it to *.rst, while you're writing
> it, and see what:
> 	make htmldocs
> will complain and how it will look in html.

So, no complaints from Sphinx and the HTML output looks good IMO. Was
there anything specific you had in mind when saying that Sphinx would
complain?

Regards,

   Wolfram

[toc] | [next] | [standalone]

#1735986

[Multipart message — attachments visible in raw view] — view raw

Em Wed, 20 Sep 2017 19:18:40 +0200
Wolfram Sang <wsa@the-dreams.de> escreveu:

> Hi Mauro,
> 
> > > +Linux I2C and DMA
> > > +-----------------  
> > 
> > I would use, instead:
> > 
> > =================
> > Linux I2C and DMA
> > =================
> > 
> > As this is the way we're starting document titles, after converted to
> > ReST. So, better to have it already using the right format, as one day  
> 
> I did this.
> 
> > There are also a couple of things here that Sphinx would complain.  
> 
> The only complaint I got was
> 
> 	WARNING: document isn't included in any toctree
> 
> which makes sense because I renamed it only temporarily to *.rst

Yeah, that is expected.

> > So, it could be worth to rename it to *.rst, while you're writing
> > it, and see what:
> > 	make htmldocs
> > will complain and how it will look in html.  
> 
> So, no complaints from Sphinx and the HTML output looks good IMO. Was
> there anything specific you had in mind when saying that Sphinx would
> complain?

Perhaps my comments weren't clear enough. Sorry! I didn't actually 
tried to parse it with Sphinx. Just wanted to hint you about that,
as testing the docs with Sphinx could be useful when writing
documentation. 

Usually, things like function declarations produce warnings if they
contain pointers, e. g. something like:

	foo(void *bar);

as asterisks mean italics. It would complain about the lack of
an end asterisk.

In order to avoid that, and to place them into a box using monotonic fonts,
I usually add "::" at the preceding line, e. g.:

	::

		foo(void *bar);

or:

	some description::

		foo(void *bar)

on all functions (even the ones that don't use asterisks, as the
html output looks nicer.

I double-checked this patch: it doesn't contain anything that would
cause warnings or parse errors. Still, I would prefer to use
**not** instead of *not*, and would add the "::", but that's my
personal taste.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1736003

[Multipart message — attachments visible in raw view] — view raw

> In order to avoid that, and to place them into a box using monotonic fonts,
> I usually add "::" at the preceding line, e. g.:

Just in time: I added the '::' and will resubmit the new version in a
minute.

Thanks for the pointers!

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web