[v6,00/12] Include linux PCI docs into Sphinx TOC tree

Message ID	20190514144734.19760-1-changbin.du@gmail.com (mailing list archive)
Headers	show Return-Path: <linux-pci-owner@kernel.org> From: Changbin Du <changbin.du@gmail.com> To: bhelgaas@google.com, corbet@lwn.net Cc: linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, mchehab+samsung@kernel.org, Changbin Du <changbin.du@gmail.com> Subject: [PATCH v6 00/12] Include linux PCI docs into Sphinx TOC tree Date: Tue, 14 May 2019 22:47:22 +0800 Message-Id: <20190514144734.19760-1-changbin.du@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-pci-owner@vger.kernel.org Precedence: bulk
Series	Include linux PCI docs into Sphinx TOC tree \| expand [v6,00/12] Include linux PCI docs into Sphinx TOC tree [v6,01/12] Documentation: add Linux PCI to Sphinx TOC tree [v6,02/12] Documentation: PCI: convert pci.txt to reST [v6,03/12] Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST [v6,04/12] Documentation: PCI: convert pci-iov-howto.txt to reST [v6,05/12] Documentation: PCI: convert MSI-HOWTO.txt to reST [v6,06/12] Documentation: PCI: convert acpi-info.txt to reST [v6,07/12] Documentation: PCI: convert pci-error-recovery.txt to reST [v6,08/12] Documentation: PCI: convert pcieaer-howto.txt to reST [v6,09/12] Documentation: PCI: convert endpoint/pci-endpoint.txt to reST [v6,10/12] Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST [v6,11/12] Documentation: PCI: convert endpoint/pci-test-function.txt to reST [v6,12/12] Documentation: PCI: convert endpoint/pci-test-howto.txt to reST

Changbin Du May 14, 2019, 2:47 p.m. UTC

Hi all,

The kernel now uses Sphinx to generate intelligent and beautiful documentation
from reStructuredText files. I converted most of the Linux PCI docs to rst
format in this serias.

For you to preview, please visit below url:
http://www.bytemem.com:8080/kernel-doc/PCI/index.html

Thank you!

v2: trivial style update.
v3: update titles. (Bjorn Helgaas)
v4: fix comments from Mauro Carvalho Chehab
v5: update MAINTAINERS (Joe Perches)
v6: fix comments.

Changbin Du (12):
  Documentation: add Linux PCI to Sphinx TOC tree
  Documentation: PCI: convert pci.txt to reST
  Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST
  Documentation: PCI: convert pci-iov-howto.txt to reST
  Documentation: PCI: convert MSI-HOWTO.txt to reST
  Documentation: PCI: convert acpi-info.txt to reST
  Documentation: PCI: convert pci-error-recovery.txt to reST
  Documentation: PCI: convert pcieaer-howto.txt to reST
  Documentation: PCI: convert endpoint/pci-endpoint.txt to reST
  Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST
  Documentation: PCI: convert endpoint/pci-test-function.txt to reST
  Documentation: PCI: convert endpoint/pci-test-howto.txt to reST

 .../PCI/{acpi-info.txt => acpi-info.rst}      |  15 +-
 Documentation/PCI/endpoint/index.rst          |  13 +
 ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++---
 .../{pci-endpoint.txt => pci-endpoint.rst}    |  92 +++--
 ...est-function.txt => pci-test-function.rst} |  84 +++--
 ...{pci-test-howto.txt => pci-test-howto.rst} |  81 ++--
 Documentation/PCI/index.rst                   |  18 +
 .../PCI/{MSI-HOWTO.txt => msi-howto.rst}      |  85 +++--
 ...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++-------
 .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 161 ++++----
 Documentation/PCI/{pci.txt => pci.rst}        | 356 ++++++++----------
 .../{pcieaer-howto.txt => pcieaer-howto.rst}  | 156 +++++---
 .../{PCIEBUS-HOWTO.txt => picebus-howto.rst}  | 140 ++++---
 Documentation/index.rst                       |   1 +
 MAINTAINERS                                   |   4 +-
 include/linux/mod_devicetable.h               |  19 +
 include/linux/pci.h                           |  37 ++
 17 files changed, 938 insertions(+), 710 deletions(-)
 rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)
 create mode 100644 Documentation/PCI/endpoint/index.rst
 rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)
 rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (83%)
 rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (55%)
 rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)
 create mode 100644 Documentation/PCI/index.rst
 rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)
 rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)
 rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
 rename Documentation/PCI/{pci.txt => pci.rst} (68%)
 rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)
 rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)

Changbin Du May 20, 2019, 6:10 a.m. UTC | #1

Bjorn and Jonathan,
Could we consider to merge this serias now? Thanks.

On Tue, May 14, 2019 at 10:47:22PM +0800, Changbin Du wrote:
> Hi all,
> 
> The kernel now uses Sphinx to generate intelligent and beautiful documentation
> from reStructuredText files. I converted most of the Linux PCI docs to rst
> format in this serias.
> 
> For you to preview, please visit below url:
> http://www.bytemem.com:8080/kernel-doc/PCI/index.html
> 
> Thank you!
> 
> v2: trivial style update.
> v3: update titles. (Bjorn Helgaas)
> v4: fix comments from Mauro Carvalho Chehab
> v5: update MAINTAINERS (Joe Perches)
> v6: fix comments.
> 
> Changbin Du (12):
>   Documentation: add Linux PCI to Sphinx TOC tree
>   Documentation: PCI: convert pci.txt to reST
>   Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST
>   Documentation: PCI: convert pci-iov-howto.txt to reST
>   Documentation: PCI: convert MSI-HOWTO.txt to reST
>   Documentation: PCI: convert acpi-info.txt to reST
>   Documentation: PCI: convert pci-error-recovery.txt to reST
>   Documentation: PCI: convert pcieaer-howto.txt to reST
>   Documentation: PCI: convert endpoint/pci-endpoint.txt to reST
>   Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST
>   Documentation: PCI: convert endpoint/pci-test-function.txt to reST
>   Documentation: PCI: convert endpoint/pci-test-howto.txt to reST
> 
>  .../PCI/{acpi-info.txt => acpi-info.rst}      |  15 +-
>  Documentation/PCI/endpoint/index.rst          |  13 +
>  ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++---
>  .../{pci-endpoint.txt => pci-endpoint.rst}    |  92 +++--
>  ...est-function.txt => pci-test-function.rst} |  84 +++--
>  ...{pci-test-howto.txt => pci-test-howto.rst} |  81 ++--
>  Documentation/PCI/index.rst                   |  18 +
>  .../PCI/{MSI-HOWTO.txt => msi-howto.rst}      |  85 +++--
>  ...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++-------
>  .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 161 ++++----
>  Documentation/PCI/{pci.txt => pci.rst}        | 356 ++++++++----------
>  .../{pcieaer-howto.txt => pcieaer-howto.rst}  | 156 +++++---
>  .../{PCIEBUS-HOWTO.txt => picebus-howto.rst}  | 140 ++++---
>  Documentation/index.rst                       |   1 +
>  MAINTAINERS                                   |   4 +-
>  include/linux/mod_devicetable.h               |  19 +
>  include/linux/pci.h                           |  37 ++
>  17 files changed, 938 insertions(+), 710 deletions(-)
>  rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)
>  create mode 100644 Documentation/PCI/endpoint/index.rst
>  rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)
>  rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (83%)
>  rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (55%)
>  rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)
>  create mode 100644 Documentation/PCI/index.rst
>  rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)
>  rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)
>  rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
>  rename Documentation/PCI/{pci.txt => pci.rst} (68%)
>  rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)
>  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)
> 
> -- 
> 2.20.1
>

Mauro Carvalho Chehab May 20, 2019, 2:23 p.m. UTC | #2

Em Mon, 20 May 2019 06:10:15 +0000
Changbin Du <changbin.du@gmail.com> escreveu:

> Bjorn and Jonathan,
> Could we consider to merge this serias now? Thanks.

Before merging it, did you check if the renames won't cause broken
reference links? There were such breakages with your x86 and acpi
patch series. I'm sending the fixes right now, but it would be
great if you could run the ./scripts/documentation-file-ref-check
script and address any file name change this series would be
introducing. There's even a --fix option there that allows
to automatically fix them (you need to double-check the results).

Regards,
Mauro

> 
> On Tue, May 14, 2019 at 10:47:22PM +0800, Changbin Du wrote:
> > Hi all,
> > 
> > The kernel now uses Sphinx to generate intelligent and beautiful documentation
> > from reStructuredText files. I converted most of the Linux PCI docs to rst
> > format in this serias.
> > 
> > For you to preview, please visit below url:
> > http://www.bytemem.com:8080/kernel-doc/PCI/index.html
> > 
> > Thank you!
> > 
> > v2: trivial style update.
> > v3: update titles. (Bjorn Helgaas)
> > v4: fix comments from Mauro Carvalho Chehab
> > v5: update MAINTAINERS (Joe Perches)
> > v6: fix comments.
> > 
> > Changbin Du (12):
> >   Documentation: add Linux PCI to Sphinx TOC tree
> >   Documentation: PCI: convert pci.txt to reST
> >   Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST
> >   Documentation: PCI: convert pci-iov-howto.txt to reST
> >   Documentation: PCI: convert MSI-HOWTO.txt to reST
> >   Documentation: PCI: convert acpi-info.txt to reST
> >   Documentation: PCI: convert pci-error-recovery.txt to reST
> >   Documentation: PCI: convert pcieaer-howto.txt to reST
> >   Documentation: PCI: convert endpoint/pci-endpoint.txt to reST
> >   Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST
> >   Documentation: PCI: convert endpoint/pci-test-function.txt to reST
> >   Documentation: PCI: convert endpoint/pci-test-howto.txt to reST
> > 
> >  .../PCI/{acpi-info.txt => acpi-info.rst}      |  15 +-
> >  Documentation/PCI/endpoint/index.rst          |  13 +
> >  ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++---
> >  .../{pci-endpoint.txt => pci-endpoint.rst}    |  92 +++--
> >  ...est-function.txt => pci-test-function.rst} |  84 +++--
> >  ...{pci-test-howto.txt => pci-test-howto.rst} |  81 ++--
> >  Documentation/PCI/index.rst                   |  18 +
> >  .../PCI/{MSI-HOWTO.txt => msi-howto.rst}      |  85 +++--
> >  ...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++-------
> >  .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 161 ++++----
> >  Documentation/PCI/{pci.txt => pci.rst}        | 356 ++++++++----------
> >  .../{pcieaer-howto.txt => pcieaer-howto.rst}  | 156 +++++---
> >  .../{PCIEBUS-HOWTO.txt => picebus-howto.rst}  | 140 ++++---
> >  Documentation/index.rst                       |   1 +
> >  MAINTAINERS                                   |   4 +-
> >  include/linux/mod_devicetable.h               |  19 +
> >  include/linux/pci.h                           |  37 ++
> >  17 files changed, 938 insertions(+), 710 deletions(-)
> >  rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)
> >  create mode 100644 Documentation/PCI/endpoint/index.rst
> >  rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)
> >  rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (83%)
> >  rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (55%)
> >  rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)
> >  create mode 100644 Documentation/PCI/index.rst
> >  rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)
> >  rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)
> >  rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
> >  rename Documentation/PCI/{pci.txt => pci.rst} (68%)
> >  rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)
> >  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)
> > 
> > -- 
> > 2.20.1
> >   
> 



Thanks,
Mauro

Changbin Du May 20, 2019, 3:05 p.m. UTC | #3

On Mon, May 20, 2019 at 11:23:50AM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 20 May 2019 06:10:15 +0000
> Changbin Du <changbin.du@gmail.com> escreveu:
> 
> > Bjorn and Jonathan,
> > Could we consider to merge this serias now? Thanks.
> 
> Before merging it, did you check if the renames won't cause broken
> reference links? There were such breakages with your x86 and acpi
> patch series. I'm sending the fixes right now, but it would be
> great if you could run the ./scripts/documentation-file-ref-check
> script and address any file name change this series would be
> introducing. There's even a --fix option there that allows
> to automatically fix them (you need to double-check the results).
>
I just ran documentation-file-ref-check, and *no* broken reference found in PCI
documentation. This tool is great!

> Regards,
> Mauro
> 
> > 
> > On Tue, May 14, 2019 at 10:47:22PM +0800, Changbin Du wrote:
> > > Hi all,
> > > 
> > > The kernel now uses Sphinx to generate intelligent and beautiful documentation
> > > from reStructuredText files. I converted most of the Linux PCI docs to rst
> > > format in this serias.
> > > 
> > > For you to preview, please visit below url:
> > > http://www.bytemem.com:8080/kernel-doc/PCI/index.html
> > > 
> > > Thank you!
> > > 
> > > v2: trivial style update.
> > > v3: update titles. (Bjorn Helgaas)
> > > v4: fix comments from Mauro Carvalho Chehab
> > > v5: update MAINTAINERS (Joe Perches)
> > > v6: fix comments.
> > > 
> > > Changbin Du (12):
> > >   Documentation: add Linux PCI to Sphinx TOC tree
> > >   Documentation: PCI: convert pci.txt to reST
> > >   Documentation: PCI: convert PCIEBUS-HOWTO.txt to reST
> > >   Documentation: PCI: convert pci-iov-howto.txt to reST
> > >   Documentation: PCI: convert MSI-HOWTO.txt to reST
> > >   Documentation: PCI: convert acpi-info.txt to reST
> > >   Documentation: PCI: convert pci-error-recovery.txt to reST
> > >   Documentation: PCI: convert pcieaer-howto.txt to reST
> > >   Documentation: PCI: convert endpoint/pci-endpoint.txt to reST
> > >   Documentation: PCI: convert endpoint/pci-endpoint-cfs.txt to reST
> > >   Documentation: PCI: convert endpoint/pci-test-function.txt to reST
> > >   Documentation: PCI: convert endpoint/pci-test-howto.txt to reST
> > > 
> > >  .../PCI/{acpi-info.txt => acpi-info.rst}      |  15 +-
> > >  Documentation/PCI/endpoint/index.rst          |  13 +
> > >  ...-endpoint-cfs.txt => pci-endpoint-cfs.rst} |  99 ++---
> > >  .../{pci-endpoint.txt => pci-endpoint.rst}    |  92 +++--
> > >  ...est-function.txt => pci-test-function.rst} |  84 +++--
> > >  ...{pci-test-howto.txt => pci-test-howto.rst} |  81 ++--
> > >  Documentation/PCI/index.rst                   |  18 +
> > >  .../PCI/{MSI-HOWTO.txt => msi-howto.rst}      |  85 +++--
> > >  ...or-recovery.txt => pci-error-recovery.rst} | 287 +++++++-------
> > >  .../{pci-iov-howto.txt => pci-iov-howto.rst}  | 161 ++++----
> > >  Documentation/PCI/{pci.txt => pci.rst}        | 356 ++++++++----------
> > >  .../{pcieaer-howto.txt => pcieaer-howto.rst}  | 156 +++++---
> > >  .../{PCIEBUS-HOWTO.txt => picebus-howto.rst}  | 140 ++++---
> > >  Documentation/index.rst                       |   1 +
> > >  MAINTAINERS                                   |   4 +-
> > >  include/linux/mod_devicetable.h               |  19 +
> > >  include/linux/pci.h                           |  37 ++
> > >  17 files changed, 938 insertions(+), 710 deletions(-)
> > >  rename Documentation/PCI/{acpi-info.txt => acpi-info.rst} (96%)
> > >  create mode 100644 Documentation/PCI/endpoint/index.rst
> > >  rename Documentation/PCI/endpoint/{pci-endpoint-cfs.txt => pci-endpoint-cfs.rst} (64%)
> > >  rename Documentation/PCI/endpoint/{pci-endpoint.txt => pci-endpoint.rst} (83%)
> > >  rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (55%)
> > >  rename Documentation/PCI/endpoint/{pci-test-howto.txt => pci-test-howto.rst} (78%)
> > >  create mode 100644 Documentation/PCI/index.rst
> > >  rename Documentation/PCI/{MSI-HOWTO.txt => msi-howto.rst} (88%)
> > >  rename Documentation/PCI/{pci-error-recovery.txt => pci-error-recovery.rst} (67%)
> > >  rename Documentation/PCI/{pci-iov-howto.txt => pci-iov-howto.rst} (63%)
> > >  rename Documentation/PCI/{pci.txt => pci.rst} (68%)
> > >  rename Documentation/PCI/{pcieaer-howto.txt => pcieaer-howto.rst} (72%)
> > >  rename Documentation/PCI/{PCIEBUS-HOWTO.txt => picebus-howto.rst} (70%)
> > > 
> > > -- 
> > > 2.20.1
> > >   
> > 
> 
> 
> 
> Thanks,
> Mauro

Jonathan Corbet May 29, 2019, 10:35 p.m. UTC | #4

On Mon, 20 May 2019 06:10:15 +0000
Changbin Du <changbin.du@gmail.com> wrote:

> Bjorn and Jonathan,
> Could we consider to merge this serias now? Thanks.

Somewhat belatedly, but I think we could.  Bjorn, do you have a preference
for which tree this goes through?  I don't remember if we'd come to an
agreement on that or not, sorry...

Thanks,

jon

Bjorn Helgaas May 30, 2019, 2:56 a.m. UTC | #5

On Wed, May 29, 2019 at 04:35:10PM -0600, Jonathan Corbet wrote:
> On Mon, 20 May 2019 06:10:15 +0000
> Changbin Du <changbin.du@gmail.com> wrote:
> 
> > Bjorn and Jonathan,
> > Could we consider to merge this serias now? Thanks.
> 
> Somewhat belatedly, but I think we could.  Bjorn, do you have a preference
> for which tree this goes through?  I don't remember if we'd come to an
> agreement on that or not, sorry...

I don't have a preference.  I somehow had the impression it would go
through your tree, but I'd be happy to merge it if you'd prefer.

Bjorn

Bjorn Helgaas May 30, 2019, 3:01 a.m. UTC | #6

On Wed, May 29, 2019 at 04:35:10PM -0600, Jonathan Corbet wrote:
> On Mon, 20 May 2019 06:10:15 +0000
> Changbin Du <changbin.du@gmail.com> wrote:
> 
> > Bjorn and Jonathan,
> > Could we consider to merge this serias now? Thanks.
> 
> Somewhat belatedly, but I think we could.  Bjorn, do you have a preference
> for which tree this goes through?  I don't remember if we'd come to an
> agreement on that or not, sorry...

Actually, let me at least take a look at these.  I noticed that
renames caused some of the ACPI docs to end up with lines >80 columns,
and I'd prefer to avoid that.  So maybe I'll take these after all if
that's OK.

Bjorn

Bjorn Helgaas May 30, 2019, 1:04 p.m. UTC | #7

On Wed, May 29, 2019 at 10:01:39PM -0500, Bjorn Helgaas wrote:
> On Wed, May 29, 2019 at 04:35:10PM -0600, Jonathan Corbet wrote:
> > On Mon, 20 May 2019 06:10:15 +0000
> > Changbin Du <changbin.du@gmail.com> wrote:
> > 
> > > Bjorn and Jonathan,
> > > Could we consider to merge this serias now? Thanks.
> > 
> > Somewhat belatedly, but I think we could.  Bjorn, do you have a preference
> > for which tree this goes through?  I don't remember if we'd come to an
> > agreement on that or not, sorry...
> 
> Actually, let me at least take a look at these.  I noticed that
> renames caused some of the ACPI docs to end up with lines >80 columns,
> and I'd prefer to avoid that.  So maybe I'll take these after all if
> that's OK.

I applied these to pci/docs for v5.3, thanks!

[v6,00/12] Include linux PCI docs into Sphinx TOC tree

Message

Comments