[PATCH 0/4] docs: bpf: Fix RST conversion

[PATCH 0/4] docs: bpf: Fix RST conversion

[Tobin C. Harding]

Recently BPF docs were converted to RST format.  A couple of things were
missed.

 - Use 'index.rst' instead of 'README.rst'.  Although README.rst will
   work just fine it is more typical to keep the subdirectory indices
   in a file called 'index.rst'.

 - Integrate files Documentation/bpf/*.rst into build system using
   toctree in Documentation/bpf/index.rst

 - Include bpf/index in top level toctree so bpf is indexed in the main
   kernel docs.

 - Make anal change to heading format (inline with rest of Documentation/).

thanks,
Tobin.


Tobin C. Harding (4):
  docs: bpf: Rename README.rst to index.rst
  docs: bpf: Add toctree to index
  docs: Add bpf/index to top level index
  docs: bpf: Capitalise document heading

 Documentation/bpf/{README.rst => index.rst} | 10 +++++-----
 Documentation/index.rst                     |  1 +
 2 files changed, 6 insertions(+), 5 deletions(-)
 rename Documentation/bpf/{README.rst => index.rst} (82%)

-- 
2.17.1

[PATCH 1/4] docs: bpf: Rename README.rst to index.rst

[Tobin C. Harding]

Recently bpf/ docs were converted to us RST format.  'README.rst' was
created but in order to fit in with the Sphinx build system this file
should be named 'index.rst'.  Rename file, fixes to integrate into Sphinx
build system in following patches.

docs: Rename Documentation/bpf/README.rst to Documentation/bpf/index.rst

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 Documentation/bpf/{README.rst => index.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/bpf/{README.rst => index.rst} (100%)

diff --git a/Documentation/bpf/README.rst b/Documentation/bpf/index.rst
similarity index 100%
rename from Documentation/bpf/README.rst
rename to Documentation/bpf/index.rst
-- 
2.17.1

Re: [PATCH 1/4] docs: bpf: Rename README.rst to index.rst

[Sergei Shtylyov]

Hello!

On 7/25/2018 5:29 AM, Tobin C. Harding wrote:

> Recently bpf/ docs were converted to us RST format.  'README.rst' was

    s/us/use/?

> created but in order to fit in with the Sphinx build system this file
> should be named 'index.rst'.  Rename file, fixes to integrate into Sphinx
> build system in following patches.
> 
> docs: Rename Documentation/bpf/README.rst to Documentation/bpf/index.rst
> 
> Signed-off-by: Tobin C. Harding <me@tobin.cc>
[...]

MBR, Sergei

Re: [PATCH 1/4] docs: bpf: Rename README.rst to index.rst

[Tobin C. Harding]

On Wed, Jul 25, 2018 at 12:29:10PM +0300, Sergei Shtylyov wrote:
> Hello!
> 
> On 7/25/2018 5:29 AM, Tobin C. Harding wrote:
> 
> > Recently bpf/ docs were converted to us RST format.  'README.rst' was
> 
>    s/us/use/?

Thanks for the review Sergei, will fix and re-spin.

> > created but in order to fit in with the Sphinx build system this file
> > should be named 'index.rst'.  Rename file, fixes to integrate into Sphinx
> > build system in following patches.
> > 
> > docs: Rename Documentation/bpf/README.rst to Documentation/bpf/index.rst
> > 
> > Signed-off-by: Tobin C. Harding <me@tobin.cc>
> [...]
> 
> MBR, Sergei

What does MBR stand for please (not master boot record I'm guessing)?


	Tobin

Re: [PATCH 1/4] docs: bpf: Rename README.rst to index.rst

[Sergei Shtylyov]

On 7/26/2018 1:28 AM, Tobin C. Harding wrote:

>>> Recently bpf/ docs were converted to us RST format.  'README.rst' was
>>
>>     s/us/use/?
> 
> Thanks for the review Sergei, will fix and re-spin.

    Perhaps could be fixed while applying...

>>> created but in order to fit in with the Sphinx build system this file
>>> should be named 'index.rst'.  Rename file, fixes to integrate into Sphinx
>>> build system in following patches.
>>>
>>> docs: Rename Documentation/bpf/README.rst to Documentation/bpf/index.rst
>>>
>>> Signed-off-by: Tobin C. Harding <me@tobin.cc>
>> [...]
>>
>> MBR, Sergei
> 
> What does MBR stand for please (not master boot record I'm guessing)?

    My best regards. :-)

> 	Tobin

MBR, Sergei

[PATCH 2/4] docs: bpf: Add toctree to index

[Tobin C. Harding]

Recently bpf/ docs were converted to us RST format.  bp/index.rst was
created out of README but toctree was not added to include files within
Documentation/bpf/

Add toctree to Documentation/bpf/index.rst

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 Documentation/bpf/index.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index b9a80c9e9392..ab2ff13a809b 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -22,14 +22,14 @@ Frequently asked questions (FAQ)
 
 Two sets of Questions and Answers (Q&A) are maintained.
 
-* QA for common questions about BPF see: bpf_design_QA_
+.. toctree::
+   :maxdepth: 1
 
-* QA for developers interacting with BPF subsystem: bpf_devel_QA_
+   bpf_design_QA
+   bpf_devel_QA
 
 
 .. Links:
-.. _bpf_design_QA: bpf_design_QA.rst
-.. _bpf_devel_QA:  bpf_devel_QA.rst
 .. _Documentation/networking/filter.txt: ../networking/filter.txt
 .. _man-pages: https://www.kernel.org/doc/man-pages/
 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
-- 
2.17.1

[PATCH 3/4] docs: Add bpf/index to top level index

[Tobin C. Harding]

Recently bpf docs were converted to RST format.  The new files were not
added to the top level toctree.  This causes build system to emit a
warning of type

	WARNING: document isn't included in any toctree

Add bpf/index.rst to Documentation/index.rst

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 Documentation/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 5d310d960f82..24339a9c2ef8 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -92,6 +92,7 @@ needed).
    crypto/index
    filesystems/index
    vm/index
+   bpf/index
 
 Architecture-specific documentation
 -----------------------------------
-- 
2.17.1

[PATCH 4/4] docs: bpf: Capitalise document heading

[Tobin C. Harding]

The majority of files in the kernel documentation index use
capitalisation for all words, especially the shorter ones.  BPF docs
better fit in with the rest of the documentation if the heading is all
capitalised.

Capitalise document heading.

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 Documentation/bpf/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index ab2ff13a809b..00a8450a602f 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -1,5 +1,5 @@
 =================
-BPF documentation
+BPF Documentation
 =================
 
 This directory contains documentation for the BPF (Berkeley Packet
-- 
2.17.1