[PATCH 0/2] Documentation: Convert sysfs-pci to ReST

[PATCH 0/2] Documentation: Convert sysfs-pci to ReST

[Vitor Massaru Iha]

Vitor Massaru Iha (2):
  Documentation: filesystems: Convert sysfs-pci to ReST
  Documentation: filesystems: remove whitespaces

 .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
 1 file changed, 24 insertions(+), 20 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)

-- 
2.21.1

[PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Vitor Massaru Iha]

Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
---
 .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
 1 file changed, 22 insertions(+), 18 deletions(-)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)

diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.rst
similarity index 82%
rename from Documentation/filesystems/sysfs-pci.txt
rename to Documentation/filesystems/sysfs-pci.rst
index 06f1d64c6f70..9b93e7444b15 100644
--- a/Documentation/filesystems/sysfs-pci.txt
+++ b/Documentation/filesystems/sysfs-pci.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
 Accessing PCI device resources through sysfs
---------------------------------------------
+============================================
 
 sysfs, usually mounted at /sys, provides access to PCI resources on platforms
 that support it.  For example, a given bus might look like this:
@@ -30,23 +33,24 @@ This bus contains a single function device in slot 0.  The domain and bus
 numbers are reproduced for convenience.  Under the device directory are several
 files, each with their own function.
 
-       file		   function
-       ----		   --------
-       class		   PCI class (ascii, ro)
-       config		   PCI config space (binary, rw)
-       device		   PCI device (ascii, ro)
-       enable	           Whether the device is enabled (ascii, rw)
-       irq		   IRQ number (ascii, ro)
-       local_cpus	   nearby CPU mask (cpumask, ro)
-       remove		   remove device from kernel's list (ascii, wo)
-       resource		   PCI resource host addresses (ascii, ro)
-       resource0..N	   PCI resource N, if present (binary, mmap, rw[1])
-       resource0_wc..N_wc  PCI WC map resource N, if prefetchable (binary, mmap)
-       revision		   PCI revision (ascii, ro)
-       rom		   PCI ROM resource, if present (binary, ro)
-       subsystem_device	   PCI subsystem device (ascii, ro)
-       subsystem_vendor	   PCI subsystem vendor (ascii, ro)
-       vendor		   PCI vendor (ascii, ro)
+	file		    function
+	=================== ======================================================
+	class		    PCI class (ascii, ro)
+	config		    PCI config space (binary, rw)
+	device		    PCI device (ascii, ro)
+	enable		    Whether the device is enabled (ascii, rw)
+	irq		    IRQ number (ascii, ro)
+	local_cpus	    nearby CPU mask (cpumask, ro)
+	remove		    remove device from kernel's list (ascii, wo)
+	resource	    PCI resource host addresses (ascii, ro)
+	resource0..N	    PCI resource N, if present (binary, mmap, rw[1])
+	resource0_wc..N_wc  PCI WC map resource N, if prefetchable (binary, mmap)
+	revision	    PCI revision (ascii, ro)
+	rom		    PCI ROM resource, if present (binary, ro)
+	subsystem_device    PCI subsystem device (ascii, ro)
+	subsystem_vendor    PCI subsystem vendor (ascii, ro)
+	vendor		    PCI vendor (ascii, ro)
+	=================== ======================================================
 
   ro - read only file
   rw - file is readable and writable
-- 
2.21.1

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Jonathan Corbet]

On Tue, 31 Mar 2020 19:28:56 -0300
Vitor Massaru Iha <vitor@massaru.org> wrote:

> Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> ---
>  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
>  1 file changed, 22 insertions(+), 18 deletions(-)
>  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)

Please supply a changelog with your patches.

The conversion you have done in this file is incomplete; I suspect that
you have not actually built the docs and seen what the results look like.
There are literal blocks that you have not marked as such, as a minimum.
Please actually do a docs build (after adding this file to index.rst) and
make sure that the output is what you intended.

One other thing of note...this file dates back to before the Git era, and
while it has seen numerous tweaks since then, it's clearly outdated.  Look
at what's actually under /sys/devices/pci* compared to what's documented.
I will take the conversion without it, but what I would really like to see
would be an effort to document all of the attributes that appear there
with current kernels.

Thanks,

jon

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Vitor Massaru Iha]

On Tue, 2020-03-31 at 16:57 -0600, Jonathan Corbet wrote:
> On Tue, 31 Mar 2020 19:28:56 -0300
> Vitor Massaru Iha <vitor@massaru.org> wrote:
> 
> > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> > ---
> >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++-----
> > ----
> >  1 file changed, 22 insertions(+), 18 deletions(-)
> >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst}
> > (82%)
> 
> Please supply a changelog with your patches.
> 
> The conversion you have done in this file is incomplete; I suspect
> that
> you have not actually built the docs and seen what the results look
> like.
> There are literal blocks that you have not marked as such, as a
> minimum.
> Please actually do a docs build (after adding this file to index.rst)
> and
> make sure that the output is what you intended.
> 
> One other thing of note...this file dates back to before the Git era,
> and
> while it has seen numerous tweaks since then, it's clearly
> outdated.  Look
> at what's actually under /sys/devices/pci* compared to what's
> documented.
> I will take the conversion without it, but what I would really like
> to see
> would be an effort to document all of the attributes that appear
> there
> with current kernels.
> 
> Thanks,
> 
> jon

Thanks for the review, I will check your comments and correct themif that document is still needed.

BR,
Vitor

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Jonathan Corbet]

On Tue, 31 Mar 2020 20:03:46 -0300
Vitor Massaru Iha <vitor@massaru.org> wrote:

> Thanks for the review, I will check your comments and correct themif
> that document is still needed.

Oh we definitely still want the document; it's out of date but not overtly
wrong.

Thanks,

jon

Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Bjorn Helgaas]

On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> On Tue, 31 Mar 2020 19:28:56 -0300
> Vitor Massaru Iha <vitor@massaru.org> wrote:
>
> > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> > ---
> >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
> >  1 file changed, 22 insertions(+), 18 deletions(-)
> >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)
>
> Please supply a changelog with your patches.
>
> The conversion you have done in this file is incomplete; I suspect that
> you have not actually built the docs and seen what the results look like.
> There are literal blocks that you have not marked as such, as a minimum.
> Please actually do a docs build (after adding this file to index.rst) and
> make sure that the output is what you intended.
>
> One other thing of note...this file dates back to before the Git era, and
> while it has seen numerous tweaks since then, it's clearly outdated.  Look
> at what's actually under /sys/devices/pci* compared to what's documented.
> I will take the conversion without it, but what I would really like to see
> would be an effort to document all of the attributes that appear there
> with current kernels.

If you do go ahead and add/change content (as opposed to simply doing
the .txt -> .rst conversion), please do the conversion and the content
changes in separate patches.  That way the content changes will be
easier to review because they won't be mixed in with a lot of
mechanical .rst changes.

Bjorn

Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Vitor Massaru Iha]

On Tue, 2020-03-31 at 21:33 -0500, Bjorn Helgaas wrote:
> On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <corbet@lwn.net>
> wrote:
> > On Tue, 31 Mar 2020 19:28:56 -0300
> > Vitor Massaru Iha <vitor@massaru.org> wrote:
> > 
> > > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> > > ---
> > >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---
> > > ------
> > >  1 file changed, 22 insertions(+), 18 deletions(-)
> > >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-
> > > pci.rst} (82%)
> > 
> > Please supply a changelog with your patches.
> > 
> > The conversion you have done in this file is incomplete; I suspect
> > that
> > you have not actually built the docs and seen what the results look
> > like.
> > There are literal blocks that you have not marked as such, as a
> > minimum.
> > Please actually do a docs build (after adding this file to
> > index.rst) and
> > make sure that the output is what you intended.
> > 
> > One other thing of note...this file dates back to before the Git
> > era, and
> > while it has seen numerous tweaks since then, it's clearly
> > outdated.  Look
> > at what's actually under /sys/devices/pci* compared to what's
> > documented.
> > I will take the conversion without it, but what I would really like
> > to see
> > would be an effort to document all of the attributes that appear
> > there
> > with current kernels.
> 
> If you do go ahead and add/change content (as opposed to simply doing
> the .txt -> .rst conversion), please do the conversion and the
> content
> changes in separate patches.  That way the content changes will be
> easier to review because they won't be mixed in with a lot of
> mechanical .rst changes.
> 
> Bjorn

Sure, thanks for the review.

BR,
Vitor

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Matthew Wilcox]

On Tue, Mar 31, 2020 at 07:28:56PM -0300, Vitor Massaru Iha wrote:
> Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> ---
>  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
>  1 file changed, 22 insertions(+), 18 deletions(-)
>  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)
> 
> diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.rst

In addition to Jon's comments, for the next version, I would suggest
cc'ing the linux-pci@vger.kernel.org mailing list.  

Also, maybe add:

F: Documentation/filesystems/sysfs-pci.rst

to the 'PCI SUBSYSTEM' section of MAINTAINERS.

Re: [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

[Vitor Massaru Iha]

On Tue, 2020-03-31 at 17:04 -0700, Matthew Wilcox wrote:
> On Tue, Mar 31, 2020 at 07:28:56PM -0300, Vitor Massaru Iha wrote:
> > Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
> > ---
> >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++-----
> > ----
> >  1 file changed, 22 insertions(+), 18 deletions(-)
> >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst}
> > (82%)
> > 
> > diff --git a/Documentation/filesystems/sysfs-pci.txt
> > b/Documentation/filesystems/sysfs-pci.rst
> 
> In addition to Jon's comments, for the next version, I would suggest
> cc'ing the linux-pci@vger.kernel.org mailing list.  
> 
> Also, maybe add:
> 
> F: Documentation/filesystems/sysfs-pci.rst
> 
> to the 'PCI SUBSYSTEM' section of MAINTAINERS.

Thanks Matthew.

[PATCH 2/2] Documentation: filesystems: remove whitespaces

[Vitor Massaru Iha]

Signed-off-by: Vitor Massaru Iha <vitor@massaru.org>
---
 Documentation/filesystems/sysfs-pci.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst
index 9b93e7444b15..e4df647ec9db 100644
--- a/Documentation/filesystems/sysfs-pci.rst
+++ b/Documentation/filesystems/sysfs-pci.rst
@@ -71,11 +71,11 @@ don't support mmapping of certain resources, so be sure to check the return
 value from any attempted mmap.  The most notable of these are I/O port
 resources, which also provide read/write access.
 
-The 'enable' file provides a counter that indicates how many times the device 
+The 'enable' file provides a counter that indicates how many times the device
 has been enabled.  If the 'enable' file currently returns '4', and a '1' is
 echoed into it, it will then return '5'.  Echoing a '0' into it will decrease
 the count.  Even when it returns to 0, though, some of the initialisation
-may not be reversed.  
+may not be reversed.
 
 The 'rom' file is special in that it provides read-only access to the device's
 ROM file, if available.  It's disabled by default, however, so applications
-- 
2.21.1

Re: [PATCH 0/2] Documentation: Convert sysfs-pci to ReST

[Jonathan Corbet]

On Tue, 31 Mar 2020 19:28:55 -0300
Vitor Massaru Iha <vitor@massaru.org> wrote:

> Vitor Massaru Iha (2):
>   Documentation: filesystems: Convert sysfs-pci to ReST
>   Documentation: filesystems: remove whitespaces
> 
>  .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
>  1 file changed, 24 insertions(+), 20 deletions(-)
>  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)

Thanks for working on the documentation!  I do have a few comments...

The purpose for including a cover letter on a patch series is to explain
what the series as a whole is trying to accomplish.  Without that, it's
not all the helpful.

In this case, there is no real need for a series; just clean up that
trailing whitespace while doing the conversion.  (It *is* normally good
practice to separate such conversions from other changes, but that
particular change is trivial enough that you should just do it while
you're there).

When you convert a file to RST, you need to add it to the index.rst file
as well so that it can be a part of the documentation build.

Thanks,

jon

Re: [PATCH 0/2] Documentation: Convert sysfs-pci to ReST

[Joe Perches]

On Tue, 2020-03-31 at 16:49 -0600, Jonathan Corbet wrote:
> On Tue, 31 Mar 2020 19:28:55 -0300
> Vitor Massaru Iha <vitor@massaru.org> wrote:
> 
> > Vitor Massaru Iha (2):
> >   Documentation: filesystems: Convert sysfs-pci to ReST
> >   Documentation: filesystems: remove whitespaces
> > 
> >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 44 ++++++++++---------
> >  1 file changed, 24 insertions(+), 20 deletions(-)
> >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (81%)
[]
> When you convert a file to RST, you need to add it to the index.rst file
> as well so that it can be a part of the documentation build.

And if it's in the MAINTAINERS file, update the file type too.