[0/4] docs: e100[0] fix build errors

Hi Jonathan,

I may be a little confused here, I'm getting docs build failure on
Linus' mainline, linux-next, and your docs-next but different errors.
There seems to be patches to the first two trees that are not in your
docs-next tree?

Do networking docs typically go through your tree?  Looks like
networking has done some conversion to rst that hasn't gone through your
tree.  Or else my git skills are failing.

This patch set fixes current docs build failure on Linus' mainline

commit: (ba4dbdedd3ed Merge tag 'jfs-4.18' of git://github.com/kleikamp/linux-shaggy)

(FYI this is 8 commits after Linux 4.18-rc1).

And also same build errors on today's linux-next

8439c34f07a3 (tag: next-20180621, linux-next/master, linux-next) Add linux-next specific files for 20180621

I pulled your tree, just to make sure I'm pulling the correct one I got

a49d9c0ae46e (HEAD -> docs-next, tag: docs-4.18, corbet/docs-next) Documentation: document hung_task_panic kernel parameter

I split the patches in between the two drivers to enable use of the
'Fixes:' tag.

One question, is there are standard spacing after headings.  I attempted
to maintain uniformity within each file but this has resulted in the two
files being different.  One has no space after section headings

	section heading
	---------------
	Some text with no newline.

While the other file uses a single newline after section headings.

While on the topic of newlines and headings; is there a correct number
of newlines to have _before_ a heading?

I did not find this information when looking at
Documentation/doc-guide/sphinx.rst

If there is a ruling on these newlines I can re-spin this set with an
added patch to fix all the newlines in both e1000.rst and e100.rst


thanks,
Tobin.


Tobin C. Harding (4):
  Documentation: e100: Use correct heading adornment
  Documentation: e1000: Use correct heading adornment
  Documentation: e100: Fix docs build error
  Documentation: e1000: Fix docs build error

 Documentation/networking/e100.rst  | 112 +++++++++++++++--------------
 Documentation/networking/e1000.rst |  76 ++++++++++----------
 2 files changed, 96 insertions(+), 92 deletions(-)

On Fri, 2018-06-22 at 10:37 +1000, Tobin C. Harding wrote:
> I may be a little confused here, I'm getting docs build failure on
> Linus' mainline, linux-next, and your docs-next but different errors.
> There seems to be patches to the first two trees that are not in your
> docs-next tree?
> 
> Do networking docs typically go through your tree?  Looks like
> networking has done some conversion to rst that hasn't gone through
> your
> tree.  Or else my git skills are failing.

Networking documentation changes went through David Miller's networking
tree because he maintains changes under Documentation/networking/

Hi Tobin,

On 06/21/2018 05:37 PM, Tobin C. Harding wrote:
> Hi Jonathan,
> 
> This patch set fixes current docs build failure on Linus' mainline
> 
> commit: (ba4dbdedd3ed Merge tag 'jfs-4.18' of git://github.com/kleikamp/linux-shaggy)
> 
> (FYI this is 8 commits after Linux 4.18-rc1).
> 
> And also same build errors on today's linux-next
> 
> 8439c34f07a3 (tag: next-20180621, linux-next/master, linux-next) Add linux-next specific files for 20180621
> 
> 
> I split the patches in between the two drivers to enable use of the
> 'Fixes:' tag.
> 
> Tobin C. Harding (4):
>   Documentation: e100: Use correct heading adornment
>   Documentation: e1000: Use correct heading adornment
>   Documentation: e100: Fix docs build error
>   Documentation: e1000: Fix docs build error
> 
>  Documentation/networking/e100.rst  | 112 +++++++++++++++--------------
>  Documentation/networking/e1000.rst |  76 ++++++++++----------
>  2 files changed, 96 insertions(+), 92 deletions(-)

I am still seeing a few warnings (your 4 patches applied to
linux-next-20180622):

linux-next-20180622/Documentation/networking/e100.rst:57: WARNING: Literal block expected; none found.
linux-next-20180622/Documentation/networking/e100.rst:68: WARNING: Literal block expected; none found.
linux-next-20180622/Documentation/networking/e100.rst:75: WARNING: Literal block expected; none found.
linux-next-20180622/Documentation/networking/e100.rst:84: WARNING: Literal block expected; none found.
linux-next-20180622/Documentation/networking/e100.rst:93: WARNING: Inline emphasis start-string without end-string.
linux-next-20180622/Documentation/networking/e1000.rst:83: ERROR: Unexpected indentation.
linux-next-20180622/Documentation/networking/e1000.rst:84: WARNING: Block quote ends without a blank line; unexpected unindent.
linux-next-20180622/Documentation/networking/e1000.rst:173: WARNING: Definition list ends without a blank line; unexpected unindent.
linux-next-20180622/Documentation/networking/e1000.rst:236: WARNING: Definition list ends without a blank line; unexpected unindent.


You didn't get these warnings?  or they weren't important?
or "perfect" was not your primary goal?   :)   [which is fine]

[I see around 50 similar doc formatting warnings/errors in the entire
Documentation build.]

Anyway, much better than it was.  Thanks.

Tested-by: Randy Dunlap <rdunlap@infradead.org>

From: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
Date: Fri, 22 Jun 2018 09:44:00 -0700

> On Fri, 2018-06-22 at 10:37 +1000, Tobin C. Harding wrote:
>> I may be a little confused here, I'm getting docs build failure on
>> Linus' mainline, linux-next, and your docs-next but different errors.
>> There seems to be patches to the first two trees that are not in your
>> docs-next tree?
>> 
>> Do networking docs typically go through your tree?  Looks like
>> networking has done some conversion to rst that hasn't gone through
>> your
>> tree.  Or else my git skills are failing.
> 
> Networking documentation changes went through David Miller's networking
> tree because he maintains changes under Documentation/networking/

I've applied this series of fixes to my 'net' tree, thanks everyone.

On Fri, Jun 22, 2018 at 01:22:37PM -0700, Randy Dunlap wrote:
> Hi Tobin,
> 
> On 06/21/2018 05:37 PM, Tobin C. Harding wrote:
> > Hi Jonathan,
> > 
> > This patch set fixes current docs build failure on Linus' mainline
> > 
> > commit: (ba4dbdedd3ed Merge tag 'jfs-4.18' of git://github.com/kleikamp/linux-shaggy)
> > 
> > (FYI this is 8 commits after Linux 4.18-rc1).
> > 
> > And also same build errors on today's linux-next
> > 
> > 8439c34f07a3 (tag: next-20180621, linux-next/master, linux-next) Add linux-next specific files for 20180621
> > 
> > 
> > I split the patches in between the two drivers to enable use of the
> > 'Fixes:' tag.
> > 
> > Tobin C. Harding (4):
> >   Documentation: e100: Use correct heading adornment
> >   Documentation: e1000: Use correct heading adornment
> >   Documentation: e100: Fix docs build error
> >   Documentation: e1000: Fix docs build error
> > 
> >  Documentation/networking/e100.rst  | 112 +++++++++++++++--------------
> >  Documentation/networking/e1000.rst |  76 ++++++++++----------
> >  2 files changed, 96 insertions(+), 92 deletions(-)
> 
> I am still seeing a few warnings (your 4 patches applied to
> linux-next-20180622):
> 
> linux-next-20180622/Documentation/networking/e100.rst:57: WARNING: Literal block expected; none found.
> linux-next-20180622/Documentation/networking/e100.rst:68: WARNING: Literal block expected; none found.
> linux-next-20180622/Documentation/networking/e100.rst:75: WARNING: Literal block expected; none found.
> linux-next-20180622/Documentation/networking/e100.rst:84: WARNING: Literal block expected; none found.
> linux-next-20180622/Documentation/networking/e100.rst:93: WARNING: Inline emphasis start-string without end-string.
> linux-next-20180622/Documentation/networking/e1000.rst:83: ERROR: Unexpected indentation.
> linux-next-20180622/Documentation/networking/e1000.rst:84: WARNING: Block quote ends without a blank line; unexpected unindent.
> linux-next-20180622/Documentation/networking/e1000.rst:173: WARNING: Definition list ends without a blank line; unexpected unindent.
> linux-next-20180622/Documentation/networking/e1000.rst:236: WARNING: Definition list ends without a blank line; unexpected unindent.
> 
> 
> You didn't get these warnings?  or they weren't important?
> or "perfect" was not your primary goal?   :)   [which is fine]
>
> [I see around 50 similar doc formatting warnings/errors in the entire
> Documentation build.]

Thanks for testing this Randy.  You are right there are a bunch of
warnings, I did not think to grep for warnings on these files - sloppy
work by me.  The series has been applied already but I'll add clearing
these warnings to my TODO list.

> Anyway, much better than it was.  Thanks.
> 
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks again,
Tobin.

> On Jun 24, 2018, at 16:41, Tobin C. Harding <me@tobin.cc> wrote:
> 
>> On Fri, Jun 22, 2018 at 01:22:37PM -0700, Randy Dunlap wrote:
>> Hi Tobin,
>> 
>>> On 06/21/2018 05:37 PM, Tobin C. Harding wrote:
>>> Hi Jonathan,
>>> 
>>> This patch set fixes current docs build failure on Linus' mainline
>>> 
>>> commit: (ba4dbdedd3ed Merge tag 'jfs-4.18' of git://github.com/kleikamp/linux-shaggy)
>>> 
>>> (FYI this is 8 commits after Linux 4.18-rc1).
>>> 
>>> And also same build errors on today's linux-next
>>> 
>>> 8439c34f07a3 (tag: next-20180621, linux-next/master, linux-next) Add linux-next specific files for 20180621
>>> 
>>> 
>>> I split the patches in between the two drivers to enable use of the
>>> 'Fixes:' tag.
>>> 
>>> Tobin C. Harding (4):
>>>  Documentation: e100: Use correct heading adornment
>>>  Documentation: e1000: Use correct heading adornment
>>>  Documentation: e100: Fix docs build error
>>>  Documentation: e1000: Fix docs build error
>>> 
>>> Documentation/networking/e100.rst  | 112 +++++++++++++++--------------
>>> Documentation/networking/e1000.rst |  76 ++++++++++----------
>>> 2 files changed, 96 insertions(+), 92 deletions(-)
>> 
>> I am still seeing a few warnings (your 4 patches applied to
>> linux-next-20180622):
>> 
>> linux-next-20180622/Documentation/networking/e100.rst:57: WARNING: Literal block expected; none found.
>> linux-next-20180622/Documentation/networking/e100.rst:68: WARNING: Literal block expected; none found.
>> linux-next-20180622/Documentation/networking/e100.rst:75: WARNING: Literal block expected; none found.
>> linux-next-20180622/Documentation/networking/e100.rst:84: WARNING: Literal block expected; none found.
>> linux-next-20180622/Documentation/networking/e100.rst:93: WARNING: Inline emphasis start-string without end-string.
>> linux-next-20180622/Documentation/networking/e1000.rst:83: ERROR: Unexpected indentation.
>> linux-next-20180622/Documentation/networking/e1000.rst:84: WARNING: Block quote ends without a blank line; unexpected unindent.
>> linux-next-20180622/Documentation/networking/e1000.rst:173: WARNING: Definition list ends without a blank line; unexpected unindent.
>> linux-next-20180622/Documentation/networking/e1000.rst:236: WARNING: Definition list ends without a blank line; unexpected unindent.
>> 
>> 
>> You didn't get these warnings?  or they weren't important?
>> or "perfect" was not your primary goal?   :)   [which is fine]
>> 
>> [I see around 50 similar doc formatting warnings/errors in the entire
>> Documentation build.]
> 
> Thanks for testing this Randy.  You are right there are a bunch of
> warnings, I did not think to grep for warnings on these files - sloppy
> work by me.  The series has been applied already but I'll add clearing
> these warnings to my TODO list.

Thanks, already on it.  I have a set of patches that I will push once Dave open’s up his net-next tree.

> 
>> Anyway, much better than it was.  Thanks.
>> 
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> 
> Thanks again,
> Tobin.

On Mon, Jun 25, 2018 at 01:11:33AM +0000, Kirsher, Jeffrey T wrote:
> 
> 
> > On Jun 24, 2018, at 16:41, Tobin C. Harding <me@tobin.cc> wrote:
> > 
> >> On Fri, Jun 22, 2018 at 01:22:37PM -0700, Randy Dunlap wrote:
> >> Hi Tobin,
> >> 
> >>> On 06/21/2018 05:37 PM, Tobin C. Harding wrote:
> >>> Hi Jonathan,
> >>> 
> >>> This patch set fixes current docs build failure on Linus' mainline
> >>> 
> >>> commit: (ba4dbdedd3ed Merge tag 'jfs-4.18' of git://github.com/kleikamp/linux-shaggy)
> >>> 
> >>> (FYI this is 8 commits after Linux 4.18-rc1).
> >>> 
> >>> And also same build errors on today's linux-next
> >>> 
> >>> 8439c34f07a3 (tag: next-20180621, linux-next/master, linux-next) Add linux-next specific files for 20180621
> >>> 
> >>> 
> >>> I split the patches in between the two drivers to enable use of the
> >>> 'Fixes:' tag.
> >>> 
> >>> Tobin C. Harding (4):
> >>>  Documentation: e100: Use correct heading adornment
> >>>  Documentation: e1000: Use correct heading adornment
> >>>  Documentation: e100: Fix docs build error
> >>>  Documentation: e1000: Fix docs build error
> >>> 
> >>> Documentation/networking/e100.rst  | 112 +++++++++++++++--------------
> >>> Documentation/networking/e1000.rst |  76 ++++++++++----------
> >>> 2 files changed, 96 insertions(+), 92 deletions(-)
> >> 
> >> I am still seeing a few warnings (your 4 patches applied to
> >> linux-next-20180622):
> >> 
> >> linux-next-20180622/Documentation/networking/e100.rst:57: WARNING: Literal block expected; none found.
> >> linux-next-20180622/Documentation/networking/e100.rst:68: WARNING: Literal block expected; none found.
> >> linux-next-20180622/Documentation/networking/e100.rst:75: WARNING: Literal block expected; none found.
> >> linux-next-20180622/Documentation/networking/e100.rst:84: WARNING: Literal block expected; none found.
> >> linux-next-20180622/Documentation/networking/e100.rst:93: WARNING: Inline emphasis start-string without end-string.
> >> linux-next-20180622/Documentation/networking/e1000.rst:83: ERROR: Unexpected indentation.
> >> linux-next-20180622/Documentation/networking/e1000.rst:84: WARNING: Block quote ends without a blank line; unexpected unindent.
> >> linux-next-20180622/Documentation/networking/e1000.rst:173: WARNING: Definition list ends without a blank line; unexpected unindent.
> >> linux-next-20180622/Documentation/networking/e1000.rst:236: WARNING: Definition list ends without a blank line; unexpected unindent.
> >> 
> >> 
> >> You didn't get these warnings?  or they weren't important?
> >> or "perfect" was not your primary goal?   :)   [which is fine]
> >> 
> >> [I see around 50 similar doc formatting warnings/errors in the entire
> >> Documentation build.]
> > 
> > Thanks for testing this Randy.  You are right there are a bunch of
> > warnings, I did not think to grep for warnings on these files - sloppy
> > work by me.  The series has been applied already but I'll add clearing
> > these warnings to my TODO list.
> 
> Thanks, already on it.  I have a set of patches that I will push once Dave open’s up his net-next tree.

Oh cool, even better.

thanks,
Tobin.