[PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Mauro Carvalho Chehab]

In the past, we did some efforts to ensure that almost all files under
Documentation/*.txt could be built with Sphinx.

Some regressions happened there (and some new files got added).
Fix those files in order to allow them to be able to build with Sphinx.

The changes on this series are trivial, adding the minimum stuff to allow
building those files with sphinx-build with no warnings and to make the
contents minimally consistent with other documentation files.

Mauro Carvalho Chehab (8):
  docs: DMA-API-HOWTO: add a missing "="
  docs: atomic_bitops.txt: add a title for this document
  docs: clearing-warn-once.txt: add a title for this document
  docs: ntb.txt: use Sphinx notation for the two ascii figures
  docs: unaligned-memory-access.txt: use a lowercase title
  docs: video-output.txt: convert it to ReST format
  docs: ntb.txt: add blank lines to clean up some Sphinx warnings
  docs: speculation.txt: mark example blocks as such

 Documentation/DMA-API-HOWTO.txt           |  2 +-
 Documentation/atomic_bitops.txt           |  6 +--
 Documentation/clearing-warn-once.txt      |  2 +
 Documentation/ntb.txt                     | 14 ++++--
 Documentation/speculation.txt             |  8 ++--
 Documentation/unaligned-memory-access.txt |  2 +-
 Documentation/video-output.txt            | 52 +++++++++++------------
 7 files changed, 47 insertions(+), 39 deletions(-)

-- 
2.20.1

[PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Mauro Carvalho Chehab]

In the past, we did some efforts to ensure that almost all files under
Documentation/*.txt could be built with Sphinx.

Some regressions happened there (and some new files got added).
Fix those files in order to allow them to be able to build with Sphinx.

The changes on this series are trivial, adding the minimum stuff to allow
building those files with sphinx-build with no warnings and to make the
contents minimally consistent with other documentation files.

Mauro Carvalho Chehab (8):
  docs: DMA-API-HOWTO: add a missing "="
  docs: atomic_bitops.txt: add a title for this document
  docs: clearing-warn-once.txt: add a title for this document
  docs: ntb.txt: use Sphinx notation for the two ascii figures
  docs: unaligned-memory-access.txt: use a lowercase title
  docs: video-output.txt: convert it to ReST format
  docs: ntb.txt: add blank lines to clean up some Sphinx warnings
  docs: speculation.txt: mark example blocks as such

 Documentation/DMA-API-HOWTO.txt           |  2 +-
 Documentation/atomic_bitops.txt           |  6 +--
 Documentation/clearing-warn-once.txt      |  2 +
 Documentation/ntb.txt                     | 14 ++++--
 Documentation/speculation.txt             |  8 ++--
 Documentation/unaligned-memory-access.txt |  2 +-
 Documentation/video-output.txt            | 52 +++++++++++------------
 7 files changed, 47 insertions(+), 39 deletions(-)

-- 
2.20.1

[PATCH 2/8] docs: atomic_bitops.txt: add a title for this document

[Mauro Carvalho Chehab]

This document misses a title. Add it, in order to follow
the documentation standard.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/atomic_bitops.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt
index be70b32c95d9..093cdaefdb37 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.txt
@@ -1,6 +1,6 @@
-
-On atomic bitops.
-
+=============
+Atomic bitops
+=============
 
 While our bitmap_{}() functions are non-atomic, we have a number of operations
 operating on single bits in a bitmap that are atomic.
-- 
2.20.1

[PATCH 2/8] docs: atomic_bitops.txt: add a title for this document

[Mauro Carvalho Chehab]

This document misses a title. Add it, in order to follow
the documentation standard.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/atomic_bitops.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt
index be70b32c95d9..093cdaefdb37 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.txt
@@ -1,6 +1,6 @@
-
-On atomic bitops.
-
+=============
+Atomic bitops
+=============
 
 While our bitmap_{}() functions are non-atomic, we have a number of operations
 operating on single bits in a bitmap that are atomic.
-- 
2.20.1

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Wed, 10 Apr 2019 06:56:19 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.
> 
> Some regressions happened there (and some new files got added).
> Fix those files in order to allow them to be able to build with Sphinx.
> 
> The changes on this series are trivial, adding the minimum stuff to allow
> building those files with sphinx-build with no warnings and to make the
> contents minimally consistent with other documentation files.

I've applied this set, thanks.

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Wed, 10 Apr 2019 06:56:19 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.
> 
> Some regressions happened there (and some new files got added).
> Fix those files in order to allow them to be able to build with Sphinx.
> 
> The changes on this series are trivial, adding the minimum stuff to allow
> building those files with sphinx-build with no warnings and to make the
> contents minimally consistent with other documentation files.

I've applied this set, thanks.

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.

Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.

Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 12:21 schrieb David Howells:
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
>> In the past, we did some efforts to ensure that almost all files under
>> Documentation/*.txt could be built with Sphinx.
> 
> Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

I recommend the Sphinx reStructuredText Primer

- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Which is already named in our 'How to write kernel documentation' introduction

- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation


-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 12:21 schrieb David Howells:
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
>> In the past, we did some efforts to ensure that almost all files under
>> Documentation/*.txt could be built with Sphinx.
> 
> Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

I recommend the Sphinx reStructuredText Primer

- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Which is already named in our 'How to write kernel documentation' introduction

- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation


-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Markus Heiser <markus.heiser@darmarit.de> wrote:

> Which is already named in our 'How to write kernel documentation' introduction
> 
> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation

This should really be in Documentation/ directory.

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Markus Heiser <markus.heiser@darmarit.de> wrote:

> Which is already named in our 'How to write kernel documentation' introduction
> 
> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation

This should really be in Documentation/ directory.

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 14:19 schrieb David Howells:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Which is already named in our 'How to write kernel documentation' introduction
>>
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
> 
> This should really be in Documentation/ directory.
> 

I agree with you, it is a kind of information hiding.  If you know proper
places, please send a patch to Jon.

   -- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 14:19 schrieb David Howells:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Which is already named in our 'How to write kernel documentation' introduction
>>
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
> 
> This should really be in Documentation/ directory.
> 

I agree with you, it is a kind of information hiding.  If you know proper
places, please send a patch to Jon.

   -- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Fri, 12 Apr 2019 14:34:25 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> Am 12.04.19 um 14:19 schrieb David Howells:
> > Markus Heiser <markus.heiser@darmarit.de> wrote:
> >   
> >> Which is already named in our 'How to write kernel documentation' introduction
> >>
> >> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation  
> > 
> > This should really be in Documentation/ directory.
> >   
> 
> I agree with you, it is a kind of information hiding.  If you know proper
> places, please send a patch to Jon.

As Jani pointed out, it's in Documentation/doc-guide.

If you're saying it should be in the top level, I kind of disagree.
Documentation/ is an exercise in hiding information by placing it in the
middle of 200 other, unrelated files.  We've made some progress on that,
and I would like to continue to do so.

Thanks,

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Fri, 12 Apr 2019 14:34:25 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> Am 12.04.19 um 14:19 schrieb David Howells:
> > Markus Heiser <markus.heiser@darmarit.de> wrote:
> >   
> >> Which is already named in our 'How to write kernel documentation' introduction
> >>
> >> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation  
> > 
> > This should really be in Documentation/ directory.
> >   
> 
> I agree with you, it is a kind of information hiding.  If you know proper
> places, please send a patch to Jon.

As Jani pointed out, it's in Documentation/doc-guide.

If you're saying it should be in the top level, I kind of disagree.
Documentation/ is an exercise in hiding information by placing it in the
middle of 200 other, unrelated files.  We've made some progress on that,
and I would like to continue to do so.

Thanks,

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 17:39 schrieb Jonathan Corbet:
> On Fri, 12 Apr 2019 14:34:25 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Am 12.04.19 um 14:19 schrieb David Howells:
>>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>>>    
>>>> Which is already named in our 'How to write kernel documentation' introduction
>>>>
>>>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>>>
>>> This should really be in Documentation/ directory.
>>>    
>>
>> I agree with you, it is a kind of information hiding.  If you know proper
>> places, please send a patch to Jon.
> 
> As Jani pointed out, it's in Documentation/doc-guide.
> 
> If you're saying it should be in the top level, I kind of disagree.
> Documentation/ is an exercise in hiding information by placing it in the
> middle of 200 other, unrelated files.  We've made some progress on that,
> and I would like to continue to do so.

For those who are new and are willing to document, it migth be a good idea
to have a simple Documentation/README.txt  with a link to doc-guide?

Just a few words, I find with my editor, this is what I find often helpful
when I'am new to a project.

-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 17:39 schrieb Jonathan Corbet:
> On Fri, 12 Apr 2019 14:34:25 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Am 12.04.19 um 14:19 schrieb David Howells:
>>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>>>    
>>>> Which is already named in our 'How to write kernel documentation' introduction
>>>>
>>>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>>>
>>> This should really be in Documentation/ directory.
>>>    
>>
>> I agree with you, it is a kind of information hiding.  If you know proper
>> places, please send a patch to Jon.
> 
> As Jani pointed out, it's in Documentation/doc-guide.
> 
> If you're saying it should be in the top level, I kind of disagree.
> Documentation/ is an exercise in hiding information by placing it in the
> middle of 200 other, unrelated files.  We've made some progress on that,
> and I would like to continue to do so.

For those who are new and are willing to document, it migth be a good idea
to have a simple Documentation/README.txt  with a link to doc-guide?

Just a few words, I find with my editor, this is what I find often helpful
when I'am new to a project.

-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jani Nikula]

On Fri, 12 Apr 2019, David Howells <dhowells@redhat.com> wrote:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
>
>> Which is already named in our 'How to write kernel documentation' introduction
>> 
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>
> This should really be in Documentation/ directory.

It is. Documentation/doc-guide/sphinx.rst.

Just double checking, you do know that all of [1] is generated from
Documentation/ using 'make html'?

BR,
Jani.


[1] https://www.kernel.org/doc/html/latest/


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jani Nikula]

On Fri, 12 Apr 2019, David Howells <dhowells@redhat.com> wrote:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
>
>> Which is already named in our 'How to write kernel documentation' introduction
>> 
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>
> This should really be in Documentation/ directory.

It is. Documentation/doc-guide/sphinx.rst.

Just double checking, you do know that all of [1] is generated from
Documentation/ using 'make html'?

BR,
Jani.


[1] https://www.kernel.org/doc/html/latest/


-- 
Jani Nikula, Intel Open Source Graphics Center