[U-Boot,00/50] doc: Shape into useful HTML docs
mbox series

Message ID 1563435275-22326-1-git-send-email-bmeng.cn@gmail.com
Headers show
Series
  • doc: Shape into useful HTML docs
Related show

Message

Bin Meng July 18, 2019, 7:33 a.m. UTC
At present there is Sphinx doc build system in U-Boot, however the
contents are very limited, e.g.: only a few API descriptions like
EFI, are included.

This series proposes an initial Sphinx doc layout for future extension,
by converting some of the plain text documentation to reStructuredText
format and add it to Sphinx TOC tree.

With this series, now we have the following major chapters in our
U-Boot HTML doc:

- Driver Model
- U-Boot API documentation
- Architecture-specific doc
- Board-specific doc

Board specific documents are put in a vendor subdirectory, just like
what we have in <src_tree>/board. All x86 & RISC-V board docs are
converted to reST. A few other board docs are converted too.

Tested by generating the HTML docs, 0 build warnings.

This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.

@Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?

This series is available at u-boot-x86/doc for testing.


Bin Meng (50):
  doc: Move existing rst files into api sub-directory
  doc: Add top-level description about U-Boot documentation
  doc: Add driver-model to Sphinx TOC tree
  doc: driver-model: Convert README.txt to reST
  doc: driver-model: Convert MIGRATION.txt to reST
  doc: driver-model: Convert fdt-fixup.txt to reST
  doc: driver-model: Convert fs_firmware_loader.txt to reST
  doc: driver-model: Convert i2c-howto.txt to reST
  doc: driver-model: Convert livetree.txt to reST
  doc: driver-model: Convert of-plat.txt to reST
  doc: driver-model: Convert pci-info.txt to reST
  doc: driver-model: Convert pmic-framework.txt to reST
  doc: driver-model: Convert remoteproc-framework.txt to reST
  doc: driver-model: Convert serial-howto.txt to reST
  doc: driver-model: Convert spi-howto.txt to reST
  doc: driver-model: Convert usb-info.txt to reST
  doc: Add architecture specific info to Sphinx TOC tree
  doc: arch: Convert README.mips to reST
  doc: Add board specific info to Sphinx TOC tree
  doc: board: Add Intel Crown Bay board doc
  doc: board: Add Intel Bay Trail based board docs
  doc: board: Add Intel Cherry Hill board doc
  doc: board: Add Intel Cougar Canyon 2 board doc
  doc: board: Add Intel Edison board doc
  doc: board: Add Intel Galileo board doc
  doc: board: Add Google Chromebook Link board doc
  doc: board: Add Google Chromebook Samus board doc
  doc: board: Add coreboot board doc
  doc: board: Add QEMU x86 board doc
  doc: board: Convert README.qemu-arm to reST
  doc: board: Convert README.qemu-riscv to reST
  doc: board: Convert README.qemu-mips to reST
  doc: board: Add AndesTech ax25-ae350 board doc
  doc: board: Convert README.ag101p to reST
  doc: board: Convert README.sifive-fu540 to reST
  doc: board: Convert README.sh7752evb to reST
  doc: board: Convert README.sh7753evb to reST
  doc: board: Convert README.at91 to reST
  doc: board: Convert README.b4860qds to reST
  doc: board: Convert README.zynq to reST
  doc: arch: Convert README.x86 to reST
  doc: arch: Convert README.arm64 to reST
  doc: arch: Convert README.NDS32 to reST
  doc: arch: Convert README.nios2 to reST
  doc: arch: Convert README.ARC to reST
  doc: arch: Convert README.m68k to reST
  doc: arch: Convert README.sh to reST
  doc: arch: Convert README.sandbox to reST
  doc: arch: Convert README.xtensa to reST
  doc: Remove README.blackfin

 doc/README.AX25                                    |  46 --
 doc/README.N1213                                   |  55 --
 doc/README.NDS32                                   |  41 --
 doc/README.ae350                                   | 275 --------
 doc/README.at91                                    | 174 -----
 doc/README.b4860qds                                | 366 ----------
 doc/README.blackfin                                |  46 --
 doc/README.m68k                                    | 150 ----
 doc/README.qemu-mips                               | 195 ------
 doc/README.sh                                      |  97 ---
 doc/README.sh7752evb                               |  67 --
 doc/README.sh7753evb                               |  67 --
 doc/README.sifive-fu540                            | 303 --------
 doc/{ => api}/efi.rst                              |   0
 doc/api/index.rst                                  |  11 +
 doc/{ => api}/linker_lists.rst                     |   0
 doc/{ => api}/serial.rst                           |   0
 doc/{README.ARC => arch/arc.rst}                   |   5 +
 doc/{README.arm64 => arch/arm64.rst}               |  25 +-
 doc/arch/index.rst                                 |  18 +
 doc/arch/m68k.rst                                  | 170 +++++
 doc/{README.mips => arch/mips.rst}                 |  28 +-
 doc/arch/nds32.rst                                 | 101 +++
 doc/{README.nios2 => arch/nios2.rst}               |  86 ++-
 .../sandbox/README.sandbox => doc/arch/sandbox.rst | 251 +++----
 doc/arch/sh.rst                                    | 106 +++
 doc/{README.x86 => arch/x86.rst}                   | 766 ++++-----------------
 doc/{README.xtensa => arch/xtensa.rst}             |  24 +-
 .../AndesTech/adp-ag101p.rst}                      |  26 +-
 doc/board/AndesTech/ax25-ae350.rst                 | 329 +++++++++
 doc/board/atmel/at91ek.rst                         | 192 ++++++
 doc/board/coreboot/coreboot.rst                    |  42 ++
 doc/board/coreboot/index.rst                       |   9 +
 doc/board/emulation/index.rst                      |  12 +
 .../emulation/qemu-arm.rst}                        |  44 +-
 doc/board/emulation/qemu-mips.rst                  | 234 +++++++
 .../emulation/qemu-riscv.rst}                      |  21 +-
 doc/board/emulation/qemu-x86.rst                   | 101 +++
 doc/board/freescale/b4860qds.rst                   | 453 ++++++++++++
 doc/board/google/chromebook_link.rst               |  34 +
 doc/board/google/chromebook_samus.rst              | 101 +++
 doc/board/google/index.rst                         |  10 +
 doc/board/index.rst                                |  18 +
 doc/board/intel/bayleybay.rst                      |  29 +
 doc/board/intel/cherryhill.rst                     |  30 +
 doc/board/intel/cougarcanyon2.rst                  |  24 +
 doc/board/intel/crownbay.rst                       |  43 ++
 doc/board/intel/edison.rst                         |  41 ++
 doc/board/intel/galileo.rst                        |  22 +
 doc/board/intel/index.rst                          |  15 +
 doc/board/intel/minnowmax.rst                      |  70 ++
 doc/board/renesas/sh7752evb.rst                    |  79 +++
 doc/board/renesas/sh7753evb.rst                    |  79 +++
 doc/board/sifive/fu540.rst                         | 321 +++++++++
 doc/{README.zynq => board/xilinx/zynq.rst}         |  82 ++-
 doc/driver-model/{README.txt => design.rst}        | 589 ++++++++--------
 doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst}  |  56 +-
 doc/driver-model/fs_firmware_loader.rst            | 154 +++++
 doc/driver-model/fs_firmware_loader.txt            | 148 ----
 doc/driver-model/{i2c-howto.txt => i2c-howto.rst}  |  36 +-
 doc/driver-model/index.rst                         |  21 +
 doc/driver-model/{livetree.txt => livetree.rst}    |  94 +--
 doc/driver-model/{MIGRATION.txt => migration.rst}  |  44 +-
 doc/driver-model/{of-plat.txt => of-plat.rst}      | 193 +++---
 doc/driver-model/{pci-info.txt => pci-info.rst}    |  21 +-
 .../{pmic-framework.txt => pmic-framework.rst}     | 131 ++--
 ...proc-framework.txt => remoteproc-framework.rst} | 181 ++---
 .../{serial-howto.txt => serial-howto.rst}         |  12 +-
 doc/driver-model/spi-howto.rst                     | 692 +++++++++++++++++++
 doc/driver-model/spi-howto.txt                     | 623 -----------------
 doc/driver-model/{usb-info.txt => usb-info.rst}    | 184 ++---
 doc/index.rst                                      |  69 +-
 72 files changed, 4903 insertions(+), 4279 deletions(-)
 delete mode 100644 doc/README.AX25
 delete mode 100644 doc/README.N1213
 delete mode 100644 doc/README.NDS32
 delete mode 100644 doc/README.ae350
 delete mode 100644 doc/README.at91
 delete mode 100644 doc/README.b4860qds
 delete mode 100644 doc/README.blackfin
 delete mode 100644 doc/README.m68k
 delete mode 100644 doc/README.qemu-mips
 delete mode 100644 doc/README.sh
 delete mode 100644 doc/README.sh7752evb
 delete mode 100644 doc/README.sh7753evb
 delete mode 100644 doc/README.sifive-fu540
 rename doc/{ => api}/efi.rst (100%)
 create mode 100644 doc/api/index.rst
 rename doc/{ => api}/linker_lists.rst (100%)
 rename doc/{ => api}/serial.rst (100%)
 rename doc/{README.ARC => arch/arc.rst} (96%)
 rename doc/{README.arm64 => arch/arm64.rst} (83%)
 create mode 100644 doc/arch/index.rst
 create mode 100644 doc/arch/m68k.rst
 rename doc/{README.mips => arch/mips.rst} (74%)
 create mode 100644 doc/arch/nds32.rst
 rename doc/{README.nios2 => arch/nios2.rst} (51%)
 rename board/sandbox/README.sandbox => doc/arch/sandbox.rst (76%)
 create mode 100644 doc/arch/sh.rst
 rename doc/{README.x86 => arch/x86.rst} (51%)
 rename doc/{README.xtensa => arch/xtensa.rst} (90%)
 rename doc/{README.ag101p => board/AndesTech/adp-ag101p.rst} (83%)
 create mode 100644 doc/board/AndesTech/ax25-ae350.rst
 create mode 100644 doc/board/atmel/at91ek.rst
 create mode 100644 doc/board/coreboot/coreboot.rst
 create mode 100644 doc/board/coreboot/index.rst
 create mode 100644 doc/board/emulation/index.rst
 rename doc/{README.qemu-arm => board/emulation/qemu-arm.rst} (80%)
 create mode 100644 doc/board/emulation/qemu-mips.rst
 rename doc/{README.qemu-riscv => board/emulation/qemu-riscv.rst} (82%)
 create mode 100644 doc/board/emulation/qemu-x86.rst
 create mode 100644 doc/board/freescale/b4860qds.rst
 create mode 100644 doc/board/google/chromebook_link.rst
 create mode 100644 doc/board/google/chromebook_samus.rst
 create mode 100644 doc/board/google/index.rst
 create mode 100644 doc/board/index.rst
 create mode 100644 doc/board/intel/bayleybay.rst
 create mode 100644 doc/board/intel/cherryhill.rst
 create mode 100644 doc/board/intel/cougarcanyon2.rst
 create mode 100644 doc/board/intel/crownbay.rst
 create mode 100644 doc/board/intel/edison.rst
 create mode 100644 doc/board/intel/galileo.rst
 create mode 100644 doc/board/intel/index.rst
 create mode 100644 doc/board/intel/minnowmax.rst
 create mode 100644 doc/board/renesas/sh7752evb.rst
 create mode 100644 doc/board/renesas/sh7753evb.rst
 create mode 100644 doc/board/sifive/fu540.rst
 rename doc/{README.zynq => board/xilinx/zynq.rst} (53%)
 rename doc/driver-model/{README.txt => design.rst} (64%)
 rename doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} (89%)
 create mode 100644 doc/driver-model/fs_firmware_loader.rst
 delete mode 100644 doc/driver-model/fs_firmware_loader.txt
 rename doc/driver-model/{i2c-howto.txt => i2c-howto.rst} (82%)
 create mode 100644 doc/driver-model/index.rst
 rename doc/driver-model/{livetree.txt => livetree.rst} (77%)
 rename doc/driver-model/{MIGRATION.txt => migration.rst} (84%)
 rename doc/driver-model/{of-plat.txt => of-plat.rst} (65%)
 rename doc/driver-model/{pci-info.txt => pci-info.rst} (95%)
 rename doc/driver-model/{pmic-framework.txt => pmic-framework.rst} (51%)
 rename doc/driver-model/{remoteproc-framework.txt => remoteproc-framework.rst} (50%)
 rename doc/driver-model/{serial-howto.txt => serial-howto.rst} (92%)
 create mode 100644 doc/driver-model/spi-howto.rst
 delete mode 100644 doc/driver-model/spi-howto.txt
 rename doc/driver-model/{usb-info.txt => usb-info.rst} (77%)

Comments

Bin Meng July 23, 2019, 6:20 a.m. UTC | #1
Hi Tom,

On Thu, Jul 18, 2019 at 3:34 PM Bin Meng <bmeng.cn@gmail.com> wrote:
>
> At present there is Sphinx doc build system in U-Boot, however the
> contents are very limited, e.g.: only a few API descriptions like
> EFI, are included.
>
> This series proposes an initial Sphinx doc layout for future extension,
> by converting some of the plain text documentation to reStructuredText
> format and add it to Sphinx TOC tree.
>
> With this series, now we have the following major chapters in our
> U-Boot HTML doc:
>
> - Driver Model
> - U-Boot API documentation
> - Architecture-specific doc
> - Board-specific doc
>
> Board specific documents are put in a vendor subdirectory, just like
> what we have in <src_tree>/board. All x86 & RISC-V board docs are
> converted to reST. A few other board docs are converted too.
>
> Tested by generating the HTML docs, 0 build warnings.
>
> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
>
> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
>
> This series is available at u-boot-x86/doc for testing.
>

Ping?

Regards,
Bin
Wolfgang Denk July 23, 2019, 3 p.m. UTC | #2
Dear Bin,

In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote:
>
> > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> >
> > This series is available at u-boot-x86/doc for testing.
> >
>
> Ping?

Yes, this is possible.  Where can I find the HTML files?  And where
would you want to put them?  And what is the planned update
strategy?

I mean, plain HTML documents are a bit lame, as they refer to a
specific version of U-Boot only.  What if I want to see the docs for
a version of half a year ago?

What exactly are your plans?

Best regards,

Wolfgang Denk
Tom Rini July 23, 2019, 3:29 p.m. UTC | #3
On Tue, Jul 23, 2019 at 05:00:52PM +0200, Wolfgang Denk wrote:
> Dear Bin,
> 
> In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote:
> >
> > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> > >
> > > This series is available at u-boot-x86/doc for testing.
> > >
> >
> > Ping?
> 
> Yes, this is possible.  Where can I find the HTML files?  And where
> would you want to put them?  And what is the planned update
> strategy?
> 
> I mean, plain HTML documents are a bit lame, as they refer to a
> specific version of U-Boot only.  What if I want to see the docs for
> a version of half a year ago?

Thinking out loud, how about .../<VERSION>/ and we re-generate the docs
for each full release?
Bin Meng July 24, 2019, 4:53 a.m. UTC | #4
Hi Wolfgang,

On Tue, Jul 23, 2019 at 11:01 PM Wolfgang Denk <wd@denx.de> wrote:
>
> Dear Bin,
>
> In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote:
> >
> > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> > >
> > > This series is available at u-boot-x86/doc for testing.
> > >
> >
> > Ping?
>
> Yes, this is possible.  Where can I find the HTML files?  And where

The HTML files can be generated from the U-Boot source tree by "make htmldocs".

> would you want to put them?  And what is the planned update
> strategy?

If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs?

>
> I mean, plain HTML documents are a bit lame, as they refer to a
> specific version of U-Boot only.  What if I want to see the docs for
> a version of half a year ago?
>
> What exactly are your plans?

For versioned HTML, let's take a look at how Linux kernel does:
https://www.kernel.org/doc/html/

I think we can imitate Linux by having released doc archive (generated
for each release), latest doc which is nightly built that always
points to latest htmldocs in the tree. Maybe we can have additional
-rc release doc for current release (eg: v2019.10-rc1), and these -rc
htmldocs will get cleaned up when the official release is out.
Thoughts?

Regards,
Bin
Bin Meng July 24, 2019, 4:59 a.m. UTC | #5
Hi Tom,

On Tue, Jul 23, 2019 at 11:29 PM Tom Rini <trini@konsulko.com> wrote:
>
> On Tue, Jul 23, 2019 at 05:00:52PM +0200, Wolfgang Denk wrote:
> > Dear Bin,
> >
> > In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote:
> > >
> > > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> > > >
> > > > This series is available at u-boot-x86/doc for testing.
> > > >
> > >
> > > Ping?
> >
> > Yes, this is possible.  Where can I find the HTML files?  And where
> > would you want to put them?  And what is the planned update
> > strategy?
> >
> > I mean, plain HTML documents are a bit lame, as they refer to a
> > specific version of U-Boot only.  What if I want to see the docs for
> > a version of half a year ago?
>
> Thinking out loud, how about .../<VERSION>/ and we re-generate the docs
> for each full release?

If I understand correctly, you were proposing exact the same thing as
I thought, so something like:

http://denx.de/u-boot/doc/html/v2018.07/
http://denx.de/u-boot/doc/html/v2019.10-rc1/
http://denx.de/u-boot/doc/html/latest/

Anyway these are doc update strategy and has nothing to do with the
patch series itself. If no issues, could you please apply them?
I am afraid the longer time it sits in the patch queue, the
possibility of merge conflicts happen.

Regards,
Bin
Wolfgang Denk July 24, 2019, 7:08 a.m. UTC | #6
Dear Bin,

In message <CAEUhbmXhLPkyiBaMxUgjZ_dyJna_ws63WspGQuzNCtGmjqAZwQ@mail.gmail.com> you wrote:
>
> The HTML files can be generated from the U-Boot source tree by "make htmldocs".
>
> > would you want to put them?  And what is the planned update
> > strategy?
>
> If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs?

I had hoped for a bit more specific ideas.  Where _exactly_ would you
want to see them?

Speaking for myself, I would search for them under
http://www.denx.de/wiki/U-Boot/Documentation

?

> For versioned HTML, let's take a look at how Linux kernel does:
> https://www.kernel.org/doc/html/

OK, we can copy that.

Best regards,

Wolfgang Denk
Bin Meng July 24, 2019, 7:13 a.m. UTC | #7
Hi Wolfgang,

On Wed, Jul 24, 2019 at 3:08 PM Wolfgang Denk <wd@denx.de> wrote:
>
> Dear Bin,
>
> In message <CAEUhbmXhLPkyiBaMxUgjZ_dyJna_ws63WspGQuzNCtGmjqAZwQ@mail.gmail.com> you wrote:
> >
> > The HTML files can be generated from the U-Boot source tree by "make htmldocs".
> >
> > > would you want to put them?  And what is the planned update
> > > strategy?
> >
> > If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs?
>
> I had hoped for a bit more specific ideas.  Where _exactly_ would you
> want to see them?
>
> Speaking for myself, I would search for them under
> http://www.denx.de/wiki/U-Boot/Documentation
>
> ?

Sorry if I was not clear enough. Since I am not entirely sure about
the denx.de website layout I only say some rough ideas. The new Sphinx
htmldoc will have an index.html that can be hooked into a URL.

>
> > For versioned HTML, let's take a look at how Linux kernel does:
> > https://www.kernel.org/doc/html/
>
> OK, we can copy that.

I assume you already got my idea :)

Regards,
Bin
Tom Rini July 24, 2019, 2:14 p.m. UTC | #8
On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:

> At present there is Sphinx doc build system in U-Boot, however the
> contents are very limited, e.g.: only a few API descriptions like
> EFI, are included.
> 
> This series proposes an initial Sphinx doc layout for future extension,
> by converting some of the plain text documentation to reStructuredText
> format and add it to Sphinx TOC tree.
> 
> With this series, now we have the following major chapters in our
> U-Boot HTML doc:
> 
> - Driver Model
> - U-Boot API documentation
> - Architecture-specific doc
> - Board-specific doc
> 
> Board specific documents are put in a vendor subdirectory, just like
> what we have in <src_tree>/board. All x86 & RISC-V board docs are
> converted to reST. A few other board docs are converted too.
> 
> Tested by generating the HTML docs, 0 build warnings.
> 
> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
> 
> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> 
> This series is available at u-boot-x86/doc for testing.

As a follow-up, please update .gitlab-ci.yml at least to include a run
of "make htmldocs".  If we need to update the Dockerfile to include new
utils we can do that too, thanks!
Bin Meng July 24, 2019, 2:16 p.m. UTC | #9
Hi Tom,

On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote:
>
> On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:
>
> > At present there is Sphinx doc build system in U-Boot, however the
> > contents are very limited, e.g.: only a few API descriptions like
> > EFI, are included.
> >
> > This series proposes an initial Sphinx doc layout for future extension,
> > by converting some of the plain text documentation to reStructuredText
> > format and add it to Sphinx TOC tree.
> >
> > With this series, now we have the following major chapters in our
> > U-Boot HTML doc:
> >
> > - Driver Model
> > - U-Boot API documentation
> > - Architecture-specific doc
> > - Board-specific doc
> >
> > Board specific documents are put in a vendor subdirectory, just like
> > what we have in <src_tree>/board. All x86 & RISC-V board docs are
> > converted to reST. A few other board docs are converted too.
> >
> > Tested by generating the HTML docs, 0 build warnings.
> >
> > This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
> >
> > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> >
> > This series is available at u-boot-x86/doc for testing.
>
> As a follow-up, please update .gitlab-ci.yml at least to include a run
> of "make htmldocs".  If we need to update the Dockerfile to include new
> utils we can do that too, thanks!

Yes, but I will need some time to study GitLab's .gitlab-ci.yml :)

Could that be done later?

Regards,
Bin
Tom Rini July 24, 2019, 2:18 p.m. UTC | #10
On Wed, Jul 24, 2019 at 10:16:31PM +0800, Bin Meng wrote:
> Hi Tom,
> 
> On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote:
> >
> > On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:
> >
> > > At present there is Sphinx doc build system in U-Boot, however the
> > > contents are very limited, e.g.: only a few API descriptions like
> > > EFI, are included.
> > >
> > > This series proposes an initial Sphinx doc layout for future extension,
> > > by converting some of the plain text documentation to reStructuredText
> > > format and add it to Sphinx TOC tree.
> > >
> > > With this series, now we have the following major chapters in our
> > > U-Boot HTML doc:
> > >
> > > - Driver Model
> > > - U-Boot API documentation
> > > - Architecture-specific doc
> > > - Board-specific doc
> > >
> > > Board specific documents are put in a vendor subdirectory, just like
> > > what we have in <src_tree>/board. All x86 & RISC-V board docs are
> > > converted to reST. A few other board docs are converted too.
> > >
> > > Tested by generating the HTML docs, 0 build warnings.
> > >
> > > This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
> > >
> > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> > >
> > > This series is available at u-boot-x86/doc for testing.
> >
> > As a follow-up, please update .gitlab-ci.yml at least to include a run
> > of "make htmldocs".  If we need to update the Dockerfile to include new
> > utils we can do that too, thanks!
> 
> Yes, but I will need some time to study GitLab's .gitlab-ci.yml :)
> 
> Could that be done later?

Yes, to be clear, I asked for a follow-up as I have this otherwise
merged locally but can't test it since make htmldocs blows up about a
lack of required tools that I don't see documented.  Once my current
pipeline finishes (of other changes) I'll push this.
Heinrich Schuchardt July 24, 2019, 7:30 p.m. UTC | #11
On 7/24/19 4:18 PM, Tom Rini wrote:
> On Wed, Jul 24, 2019 at 10:16:31PM +0800, Bin Meng wrote:
>> Hi Tom,
>>
>> On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote:
>>>
>>> On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:
>>>
>>>> At present there is Sphinx doc build system in U-Boot, however the
>>>> contents are very limited, e.g.: only a few API descriptions like
>>>> EFI, are included.
>>>>
>>>> This series proposes an initial Sphinx doc layout for future extension,
>>>> by converting some of the plain text documentation to reStructuredText
>>>> format and add it to Sphinx TOC tree.
>>>>
>>>> With this series, now we have the following major chapters in our
>>>> U-Boot HTML doc:
>>>>
>>>> - Driver Model
>>>> - U-Boot API documentation
>>>> - Architecture-specific doc
>>>> - Board-specific doc
>>>>
>>>> Board specific documents are put in a vendor subdirectory, just like
>>>> what we have in <src_tree>/board. All x86 & RISC-V board docs are
>>>> converted to reST. A few other board docs are converted too.
>>>>
>>>> Tested by generating the HTML docs, 0 build warnings.
>>>>
>>>> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
>>>>
>>>> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
>>>>
>>>> This series is available at u-boot-x86/doc for testing.
>>>
>>> As a follow-up, please update .gitlab-ci.yml at least to include a run
>>> of "make htmldocs".  If we need to update the Dockerfile to include new
>>> utils we can do that too, thanks!
>>
>> Yes, but I will need some time to study GitLab's .gitlab-ci.yml :)
>>
>> Could that be done later?
>
> Yes, to be clear, I asked for a follow-up as I have this otherwise
> merged locally but can't test it since make htmldocs blows up about a
> lack of required tools that I don't see documented.  Once my current
> pipeline finishes (of other changes) I'll push this.
>

Hello Tom,

the necessary packages for Ubuntu Bionic to run 'make htmldocs' are:

build-essential sphinx-doc python3-sphinx

A warning occurs requesting packages graphviz and imagemagick.

Graphviz is currently not installable via apt-get but as we currently
have no graphics in our documentation you can simply ignore the warnings.

Cf.
https://www.katrinasiegfried.com/single-post/2018/10/24/Installing-GraphViz-on-Linux-Ubuntu-1804LTS

The ReadTheDocs theme can be installed via

git clone https://github.com/readthedocs/sphinx_rtd_theme
cd sphinx_rtd_theme/
sudo apt-get install python3-setuptools
python3 setup.py install

This theme is not really needed but the output looks much nicer.

The generated documentation is available under doc/output/.

Best regards

Heinrich
Tom Rini July 24, 2019, 8:05 p.m. UTC | #12
On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:

> At present there is Sphinx doc build system in U-Boot, however the
> contents are very limited, e.g.: only a few API descriptions like
> EFI, are included.
> 
> This series proposes an initial Sphinx doc layout for future extension,
> by converting some of the plain text documentation to reStructuredText
> format and add it to Sphinx TOC tree.
> 
> With this series, now we have the following major chapters in our
> U-Boot HTML doc:
> 
> - Driver Model
> - U-Boot API documentation
> - Architecture-specific doc
> - Board-specific doc
> 
> Board specific documents are put in a vendor subdirectory, just like
> what we have in <src_tree>/board. All x86 & RISC-V board docs are
> converted to reST. A few other board docs are converted too.
> 
> Tested by generating the HTML docs, 0 build warnings.
> 
> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
> 
> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> 
> This series is available at u-boot-x86/doc for testing.
> 
> 
> Bin Meng (50):
>   doc: Move existing rst files into api sub-directory
>   doc: Add top-level description about U-Boot documentation
>   doc: Add driver-model to Sphinx TOC tree
>   doc: driver-model: Convert README.txt to reST
>   doc: driver-model: Convert MIGRATION.txt to reST
>   doc: driver-model: Convert fdt-fixup.txt to reST
>   doc: driver-model: Convert fs_firmware_loader.txt to reST
>   doc: driver-model: Convert i2c-howto.txt to reST
>   doc: driver-model: Convert livetree.txt to reST
>   doc: driver-model: Convert of-plat.txt to reST
>   doc: driver-model: Convert pci-info.txt to reST
>   doc: driver-model: Convert pmic-framework.txt to reST
>   doc: driver-model: Convert remoteproc-framework.txt to reST
>   doc: driver-model: Convert serial-howto.txt to reST
>   doc: driver-model: Convert spi-howto.txt to reST
>   doc: driver-model: Convert usb-info.txt to reST
>   doc: Add architecture specific info to Sphinx TOC tree
>   doc: arch: Convert README.mips to reST
>   doc: Add board specific info to Sphinx TOC tree
>   doc: board: Add Intel Crown Bay board doc
>   doc: board: Add Intel Bay Trail based board docs
>   doc: board: Add Intel Cherry Hill board doc
>   doc: board: Add Intel Cougar Canyon 2 board doc
>   doc: board: Add Intel Edison board doc
>   doc: board: Add Intel Galileo board doc
>   doc: board: Add Google Chromebook Link board doc
>   doc: board: Add Google Chromebook Samus board doc
>   doc: board: Add coreboot board doc
>   doc: board: Add QEMU x86 board doc
>   doc: board: Convert README.qemu-arm to reST
>   doc: board: Convert README.qemu-riscv to reST
>   doc: board: Convert README.qemu-mips to reST
>   doc: board: Add AndesTech ax25-ae350 board doc
>   doc: board: Convert README.ag101p to reST
>   doc: board: Convert README.sifive-fu540 to reST
>   doc: board: Convert README.sh7752evb to reST
>   doc: board: Convert README.sh7753evb to reST
>   doc: board: Convert README.at91 to reST
>   doc: board: Convert README.b4860qds to reST
>   doc: board: Convert README.zynq to reST
>   doc: arch: Convert README.x86 to reST
>   doc: arch: Convert README.arm64 to reST
>   doc: arch: Convert README.NDS32 to reST
>   doc: arch: Convert README.nios2 to reST
>   doc: arch: Convert README.ARC to reST
>   doc: arch: Convert README.m68k to reST
>   doc: arch: Convert README.sh to reST
>   doc: arch: Convert README.sandbox to reST
>   doc: arch: Convert README.xtensa to reST
>   doc: Remove README.blackfin

For the series, applied to u-boot/master, thanks!
Heinrich Schuchardt July 25, 2019, 6:31 p.m. UTC | #13
On 7/18/19 9:33 AM, Bin Meng wrote:
> At present there is Sphinx doc build system in U-Boot, however the
> contents are very limited, e.g.: only a few API descriptions like
> EFI, are included.
>
> This series proposes an initial Sphinx doc layout for future extension,
> by converting some of the plain text documentation to reStructuredText
> format and add it to Sphinx TOC tree.
>
> With this series, now we have the following major chapters in our
> U-Boot HTML doc:
>
> - Driver Model
> - U-Boot API documentation
> - Architecture-specific doc
> - Board-specific doc
>
> Board specific documents are put in a vendor subdirectory, just like
> what we have in <src_tree>/board. All x86 & RISC-V board docs are
> converted to reST. A few other board docs are converted too.
>
> Tested by generating the HTML docs, 0 build warnings.
>
> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
>
> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
>
> This series is available at u-boot-x86/doc for testing.
>
>
> Bin Meng (50):
>    doc: Move existing rst files into api sub-directory
>    doc: Add top-level description about U-Boot documentation
>    doc: Add driver-model to Sphinx TOC tree
>    doc: driver-model: Convert README.txt to reST
>    doc: driver-model: Convert MIGRATION.txt to reST
>    doc: driver-model: Convert fdt-fixup.txt to reST
>    doc: driver-model: Convert fs_firmware_loader.txt to reST
>    doc: driver-model: Convert i2c-howto.txt to reST
>    doc: driver-model: Convert livetree.txt to reST
>    doc: driver-model: Convert of-plat.txt to reST
>    doc: driver-model: Convert pci-info.txt to reST
>    doc: driver-model: Convert pmic-framework.txt to reST
>    doc: driver-model: Convert remoteproc-framework.txt to reST
>    doc: driver-model: Convert serial-howto.txt to reST
>    doc: driver-model: Convert spi-howto.txt to reST
>    doc: driver-model: Convert usb-info.txt to reST
>    doc: Add architecture specific info to Sphinx TOC tree
>    doc: arch: Convert README.mips to reST
>    doc: Add board specific info to Sphinx TOC tree
>    doc: board: Add Intel Crown Bay board doc
>    doc: board: Add Intel Bay Trail based board docs
>    doc: board: Add Intel Cherry Hill board doc
>    doc: board: Add Intel Cougar Canyon 2 board doc
>    doc: board: Add Intel Edison board doc
>    doc: board: Add Intel Galileo board doc
>    doc: board: Add Google Chromebook Link board doc
>    doc: board: Add Google Chromebook Samus board doc
>    doc: board: Add coreboot board doc
>    doc: board: Add QEMU x86 board doc
>    doc: board: Convert README.qemu-arm to reST
>    doc: board: Convert README.qemu-riscv to reST
>    doc: board: Convert README.qemu-mips to reST
>    doc: board: Add AndesTech ax25-ae350 board doc
>    doc: board: Convert README.ag101p to reST
>    doc: board: Convert README.sifive-fu540 to reST
>    doc: board: Convert README.sh7752evb to reST
>    doc: board: Convert README.sh7753evb to reST
>    doc: board: Convert README.at91 to reST
>    doc: board: Convert README.b4860qds to reST
>    doc: board: Convert README.zynq to reST
>    doc: arch: Convert README.x86 to reST
>    doc: arch: Convert README.arm64 to reST
>    doc: arch: Convert README.NDS32 to reST
>    doc: arch: Convert README.nios2 to reST
>    doc: arch: Convert README.ARC to reST
>    doc: arch: Convert README.m68k to reST
>    doc: arch: Convert README.sh to reST
>    doc: arch: Convert README.sandbox to reST
>    doc: arch: Convert README.xtensa to reST
>    doc: Remove README.blackfin
>
>   doc/README.AX25                                    |  46 --
>   doc/README.N1213                                   |  55 --
>   doc/README.NDS32                                   |  41 --
>   doc/README.ae350                                   | 275 --------
>   doc/README.at91                                    | 174 -----
>   doc/README.b4860qds                                | 366 ----------
>   doc/README.blackfin                                |  46 --
>   doc/README.m68k                                    | 150 ----
>   doc/README.qemu-mips                               | 195 ------
>   doc/README.sh                                      |  97 ---
>   doc/README.sh7752evb                               |  67 --
>   doc/README.sh7753evb                               |  67 --
>   doc/README.sifive-fu540                            | 303 --------
>   doc/{ => api}/efi.rst                              |   0
>   doc/api/index.rst                                  |  11 +
>   doc/{ => api}/linker_lists.rst                     |   0
>   doc/{ => api}/serial.rst                           |   0
>   doc/{README.ARC => arch/arc.rst}                   |   5 +
>   doc/{README.arm64 => arch/arm64.rst}               |  25 +-
>   doc/arch/index.rst                                 |  18 +
>   doc/arch/m68k.rst                                  | 170 +++++
>   doc/{README.mips => arch/mips.rst}                 |  28 +-
>   doc/arch/nds32.rst                                 | 101 +++
>   doc/{README.nios2 => arch/nios2.rst}               |  86 ++-
>   .../sandbox/README.sandbox => doc/arch/sandbox.rst | 251 +++----
>   doc/arch/sh.rst                                    | 106 +++
>   doc/{README.x86 => arch/x86.rst}                   | 766 ++++-----------------
>   doc/{README.xtensa => arch/xtensa.rst}             |  24 +-
>   .../AndesTech/adp-ag101p.rst}                      |  26 +-
>   doc/board/AndesTech/ax25-ae350.rst                 | 329 +++++++++
>   doc/board/atmel/at91ek.rst                         | 192 ++++++
>   doc/board/coreboot/coreboot.rst                    |  42 ++
>   doc/board/coreboot/index.rst                       |   9 +
>   doc/board/emulation/index.rst                      |  12 +
>   .../emulation/qemu-arm.rst}                        |  44 +-
>   doc/board/emulation/qemu-mips.rst                  | 234 +++++++
>   .../emulation/qemu-riscv.rst}                      |  21 +-
>   doc/board/emulation/qemu-x86.rst                   | 101 +++
>   doc/board/freescale/b4860qds.rst                   | 453 ++++++++++++
>   doc/board/google/chromebook_link.rst               |  34 +
>   doc/board/google/chromebook_samus.rst              | 101 +++
>   doc/board/google/index.rst                         |  10 +
>   doc/board/index.rst                                |  18 +
>   doc/board/intel/bayleybay.rst                      |  29 +
>   doc/board/intel/cherryhill.rst                     |  30 +
>   doc/board/intel/cougarcanyon2.rst                  |  24 +
>   doc/board/intel/crownbay.rst                       |  43 ++
>   doc/board/intel/edison.rst                         |  41 ++
>   doc/board/intel/galileo.rst                        |  22 +
>   doc/board/intel/index.rst                          |  15 +
>   doc/board/intel/minnowmax.rst                      |  70 ++
>   doc/board/renesas/sh7752evb.rst                    |  79 +++
>   doc/board/renesas/sh7753evb.rst                    |  79 +++
>   doc/board/sifive/fu540.rst                         | 321 +++++++++
>   doc/{README.zynq => board/xilinx/zynq.rst}         |  82 ++-
>   doc/driver-model/{README.txt => design.rst}        | 589 ++++++++--------
>   doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst}  |  56 +-
>   doc/driver-model/fs_firmware_loader.rst            | 154 +++++
>   doc/driver-model/fs_firmware_loader.txt            | 148 ----
>   doc/driver-model/{i2c-howto.txt => i2c-howto.rst}  |  36 +-
>   doc/driver-model/index.rst                         |  21 +
>   doc/driver-model/{livetree.txt => livetree.rst}    |  94 +--
>   doc/driver-model/{MIGRATION.txt => migration.rst}  |  44 +-
>   doc/driver-model/{of-plat.txt => of-plat.rst}      | 193 +++---
>   doc/driver-model/{pci-info.txt => pci-info.rst}    |  21 +-
>   .../{pmic-framework.txt => pmic-framework.rst}     | 131 ++--
>   ...proc-framework.txt => remoteproc-framework.rst} | 181 ++---
>   .../{serial-howto.txt => serial-howto.rst}         |  12 +-
>   doc/driver-model/spi-howto.rst                     | 692 +++++++++++++++++++
>   doc/driver-model/spi-howto.txt                     | 623 -----------------
>   doc/driver-model/{usb-info.txt => usb-info.rst}    | 184 ++---
>   doc/index.rst                                      |  69 +-
>   72 files changed, 4903 insertions(+), 4279 deletions(-)
>   delete mode 100644 doc/README.AX25
>   delete mode 100644 doc/README.N1213
>   delete mode 100644 doc/README.NDS32
>   delete mode 100644 doc/README.ae350
>   delete mode 100644 doc/README.at91
>   delete mode 100644 doc/README.b4860qds
>   delete mode 100644 doc/README.blackfin
>   delete mode 100644 doc/README.m68k
>   delete mode 100644 doc/README.qemu-mips
>   delete mode 100644 doc/README.sh
>   delete mode 100644 doc/README.sh7752evb
>   delete mode 100644 doc/README.sh7753evb
>   delete mode 100644 doc/README.sifive-fu540
>   rename doc/{ => api}/efi.rst (100%)
>   create mode 100644 doc/api/index.rst
>   rename doc/{ => api}/linker_lists.rst (100%)
>   rename doc/{ => api}/serial.rst (100%)
>   rename doc/{README.ARC => arch/arc.rst} (96%)
>   rename doc/{README.arm64 => arch/arm64.rst} (83%)
>   create mode 100644 doc/arch/index.rst
>   create mode 100644 doc/arch/m68k.rst
>   rename doc/{README.mips => arch/mips.rst} (74%)
>   create mode 100644 doc/arch/nds32.rst
>   rename doc/{README.nios2 => arch/nios2.rst} (51%)
>   rename board/sandbox/README.sandbox => doc/arch/sandbox.rst (76%)
>   create mode 100644 doc/arch/sh.rst
>   rename doc/{README.x86 => arch/x86.rst} (51%)
>   rename doc/{README.xtensa => arch/xtensa.rst} (90%)
>   rename doc/{README.ag101p => board/AndesTech/adp-ag101p.rst} (83%)
>   create mode 100644 doc/board/AndesTech/ax25-ae350.rst
>   create mode 100644 doc/board/atmel/at91ek.rst
>   create mode 100644 doc/board/coreboot/coreboot.rst
>   create mode 100644 doc/board/coreboot/index.rst
>   create mode 100644 doc/board/emulation/index.rst
>   rename doc/{README.qemu-arm => board/emulation/qemu-arm.rst} (80%)
>   create mode 100644 doc/board/emulation/qemu-mips.rst
>   rename doc/{README.qemu-riscv => board/emulation/qemu-riscv.rst} (82%)
>   create mode 100644 doc/board/emulation/qemu-x86.rst
>   create mode 100644 doc/board/freescale/b4860qds.rst
>   create mode 100644 doc/board/google/chromebook_link.rst
>   create mode 100644 doc/board/google/chromebook_samus.rst
>   create mode 100644 doc/board/google/index.rst
>   create mode 100644 doc/board/index.rst
>   create mode 100644 doc/board/intel/bayleybay.rst
>   create mode 100644 doc/board/intel/cherryhill.rst
>   create mode 100644 doc/board/intel/cougarcanyon2.rst
>   create mode 100644 doc/board/intel/crownbay.rst
>   create mode 100644 doc/board/intel/edison.rst
>   create mode 100644 doc/board/intel/galileo.rst
>   create mode 100644 doc/board/intel/index.rst
>   create mode 100644 doc/board/intel/minnowmax.rst
>   create mode 100644 doc/board/renesas/sh7752evb.rst
>   create mode 100644 doc/board/renesas/sh7753evb.rst
>   create mode 100644 doc/board/sifive/fu540.rst
>   rename doc/{README.zynq => board/xilinx/zynq.rst} (53%)
>   rename doc/driver-model/{README.txt => design.rst} (64%)
>   rename doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} (89%)
>   create mode 100644 doc/driver-model/fs_firmware_loader.rst
>   delete mode 100644 doc/driver-model/fs_firmware_loader.txt
>   rename doc/driver-model/{i2c-howto.txt => i2c-howto.rst} (82%)
>   create mode 100644 doc/driver-model/index.rst
>   rename doc/driver-model/{livetree.txt => livetree.rst} (77%)
>   rename doc/driver-model/{MIGRATION.txt => migration.rst} (84%)
>   rename doc/driver-model/{of-plat.txt => of-plat.rst} (65%)
>   rename doc/driver-model/{pci-info.txt => pci-info.rst} (95%)
>   rename doc/driver-model/{pmic-framework.txt => pmic-framework.rst} (51%)
>   rename doc/driver-model/{remoteproc-framework.txt => remoteproc-framework.rst} (50%)
>   rename doc/driver-model/{serial-howto.txt => serial-howto.rst} (92%)
>   create mode 100644 doc/driver-model/spi-howto.rst
>   delete mode 100644 doc/driver-model/spi-howto.txt
>   rename doc/driver-model/{usb-info.txt => usb-info.rst} (77%)
>

Hello Bin,

current origin/master make htmldocs gives me the following warnings:

reading sources... [100%] board/index

./cmd/efidebug.c:733: WARNING: Unexpected indentation.
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/AndesTech/index'
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/atmel/index'
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/freescale/index'
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/renesas/index'
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/sifive/index'
/doc/board/index.rst:6: WARNING: toctree contains reference to
nonexisting document 'board/xilinx/index'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /doc/board/AndesTech/adp-ag101p.rst: WARNING:
document isn't included in any toctree
/doc/board/AndesTech/ax25-ae350.rst: WARNING: document isn't included in
any toctree
/doc/board/atmel/at91ek.rst: WARNING: document isn't included in any toctree
/doc/board/freescale/b4860qds.rst: WARNING: document isn't included in
any toctree
/doc/board/renesas/sh7752evb.rst: WARNING: document isn't included in
any toctree
/doc/board/renesas/sh7753evb.rst: WARNING: document isn't included in
any toctree
/doc/board/sifive/fu540.rst: WARNING: document isn't included in any toctree
/doc/board/xilinx/zynq.rst: WARNING: document isn't included in any toctree
done

The efidebug.c one I will care about. Will you have a look at the
others, please?

Best regards

Heinrich
Bin Meng July 26, 2019, 1:54 a.m. UTC | #14
Hi Heinrich,

On Fri, Jul 26, 2019 at 2:32 AM Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> On 7/18/19 9:33 AM, Bin Meng wrote:
> > At present there is Sphinx doc build system in U-Boot, however the
> > contents are very limited, e.g.: only a few API descriptions like
> > EFI, are included.
> >
> > This series proposes an initial Sphinx doc layout for future extension,
> > by converting some of the plain text documentation to reStructuredText
> > format and add it to Sphinx TOC tree.
> >
> > With this series, now we have the following major chapters in our
> > U-Boot HTML doc:
> >
> > - Driver Model
> > - U-Boot API documentation
> > - Architecture-specific doc
> > - Board-specific doc
> >
> > Board specific documents are put in a vendor subdirectory, just like
> > what we have in <src_tree>/board. All x86 & RISC-V board docs are
> > converted to reST. A few other board docs are converted too.
> >
> > Tested by generating the HTML docs, 0 build warnings.
> >
> > This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
> >
> > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
> >
> > This series is available at u-boot-x86/doc for testing.
> >
> >
> > Bin Meng (50):
> >    doc: Move existing rst files into api sub-directory
> >    doc: Add top-level description about U-Boot documentation
> >    doc: Add driver-model to Sphinx TOC tree
> >    doc: driver-model: Convert README.txt to reST
> >    doc: driver-model: Convert MIGRATION.txt to reST
> >    doc: driver-model: Convert fdt-fixup.txt to reST
> >    doc: driver-model: Convert fs_firmware_loader.txt to reST
> >    doc: driver-model: Convert i2c-howto.txt to reST
> >    doc: driver-model: Convert livetree.txt to reST
> >    doc: driver-model: Convert of-plat.txt to reST
> >    doc: driver-model: Convert pci-info.txt to reST
> >    doc: driver-model: Convert pmic-framework.txt to reST
> >    doc: driver-model: Convert remoteproc-framework.txt to reST
> >    doc: driver-model: Convert serial-howto.txt to reST
> >    doc: driver-model: Convert spi-howto.txt to reST
> >    doc: driver-model: Convert usb-info.txt to reST
> >    doc: Add architecture specific info to Sphinx TOC tree
> >    doc: arch: Convert README.mips to reST
> >    doc: Add board specific info to Sphinx TOC tree
> >    doc: board: Add Intel Crown Bay board doc
> >    doc: board: Add Intel Bay Trail based board docs
> >    doc: board: Add Intel Cherry Hill board doc
> >    doc: board: Add Intel Cougar Canyon 2 board doc
> >    doc: board: Add Intel Edison board doc
> >    doc: board: Add Intel Galileo board doc
> >    doc: board: Add Google Chromebook Link board doc
> >    doc: board: Add Google Chromebook Samus board doc
> >    doc: board: Add coreboot board doc
> >    doc: board: Add QEMU x86 board doc
> >    doc: board: Convert README.qemu-arm to reST
> >    doc: board: Convert README.qemu-riscv to reST
> >    doc: board: Convert README.qemu-mips to reST
> >    doc: board: Add AndesTech ax25-ae350 board doc
> >    doc: board: Convert README.ag101p to reST
> >    doc: board: Convert README.sifive-fu540 to reST
> >    doc: board: Convert README.sh7752evb to reST
> >    doc: board: Convert README.sh7753evb to reST
> >    doc: board: Convert README.at91 to reST
> >    doc: board: Convert README.b4860qds to reST
> >    doc: board: Convert README.zynq to reST
> >    doc: arch: Convert README.x86 to reST
> >    doc: arch: Convert README.arm64 to reST
> >    doc: arch: Convert README.NDS32 to reST
> >    doc: arch: Convert README.nios2 to reST
> >    doc: arch: Convert README.ARC to reST
> >    doc: arch: Convert README.m68k to reST
> >    doc: arch: Convert README.sh to reST
> >    doc: arch: Convert README.sandbox to reST
> >    doc: arch: Convert README.xtensa to reST
> >    doc: Remove README.blackfin
> >
> >   doc/README.AX25                                    |  46 --
> >   doc/README.N1213                                   |  55 --
> >   doc/README.NDS32                                   |  41 --
> >   doc/README.ae350                                   | 275 --------
> >   doc/README.at91                                    | 174 -----
> >   doc/README.b4860qds                                | 366 ----------
> >   doc/README.blackfin                                |  46 --
> >   doc/README.m68k                                    | 150 ----
> >   doc/README.qemu-mips                               | 195 ------
> >   doc/README.sh                                      |  97 ---
> >   doc/README.sh7752evb                               |  67 --
> >   doc/README.sh7753evb                               |  67 --
> >   doc/README.sifive-fu540                            | 303 --------
> >   doc/{ => api}/efi.rst                              |   0
> >   doc/api/index.rst                                  |  11 +
> >   doc/{ => api}/linker_lists.rst                     |   0
> >   doc/{ => api}/serial.rst                           |   0
> >   doc/{README.ARC => arch/arc.rst}                   |   5 +
> >   doc/{README.arm64 => arch/arm64.rst}               |  25 +-
> >   doc/arch/index.rst                                 |  18 +
> >   doc/arch/m68k.rst                                  | 170 +++++
> >   doc/{README.mips => arch/mips.rst}                 |  28 +-
> >   doc/arch/nds32.rst                                 | 101 +++
> >   doc/{README.nios2 => arch/nios2.rst}               |  86 ++-
> >   .../sandbox/README.sandbox => doc/arch/sandbox.rst | 251 +++----
> >   doc/arch/sh.rst                                    | 106 +++
> >   doc/{README.x86 => arch/x86.rst}                   | 766 ++++-----------------
> >   doc/{README.xtensa => arch/xtensa.rst}             |  24 +-
> >   .../AndesTech/adp-ag101p.rst}                      |  26 +-
> >   doc/board/AndesTech/ax25-ae350.rst                 | 329 +++++++++
> >   doc/board/atmel/at91ek.rst                         | 192 ++++++
> >   doc/board/coreboot/coreboot.rst                    |  42 ++
> >   doc/board/coreboot/index.rst                       |   9 +
> >   doc/board/emulation/index.rst                      |  12 +
> >   .../emulation/qemu-arm.rst}                        |  44 +-
> >   doc/board/emulation/qemu-mips.rst                  | 234 +++++++
> >   .../emulation/qemu-riscv.rst}                      |  21 +-
> >   doc/board/emulation/qemu-x86.rst                   | 101 +++
> >   doc/board/freescale/b4860qds.rst                   | 453 ++++++++++++
> >   doc/board/google/chromebook_link.rst               |  34 +
> >   doc/board/google/chromebook_samus.rst              | 101 +++
> >   doc/board/google/index.rst                         |  10 +
> >   doc/board/index.rst                                |  18 +
> >   doc/board/intel/bayleybay.rst                      |  29 +
> >   doc/board/intel/cherryhill.rst                     |  30 +
> >   doc/board/intel/cougarcanyon2.rst                  |  24 +
> >   doc/board/intel/crownbay.rst                       |  43 ++
> >   doc/board/intel/edison.rst                         |  41 ++
> >   doc/board/intel/galileo.rst                        |  22 +
> >   doc/board/intel/index.rst                          |  15 +
> >   doc/board/intel/minnowmax.rst                      |  70 ++
> >   doc/board/renesas/sh7752evb.rst                    |  79 +++
> >   doc/board/renesas/sh7753evb.rst                    |  79 +++
> >   doc/board/sifive/fu540.rst                         | 321 +++++++++
> >   doc/{README.zynq => board/xilinx/zynq.rst}         |  82 ++-
> >   doc/driver-model/{README.txt => design.rst}        | 589 ++++++++--------
> >   doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst}  |  56 +-
> >   doc/driver-model/fs_firmware_loader.rst            | 154 +++++
> >   doc/driver-model/fs_firmware_loader.txt            | 148 ----
> >   doc/driver-model/{i2c-howto.txt => i2c-howto.rst}  |  36 +-
> >   doc/driver-model/index.rst                         |  21 +
> >   doc/driver-model/{livetree.txt => livetree.rst}    |  94 +--
> >   doc/driver-model/{MIGRATION.txt => migration.rst}  |  44 +-
> >   doc/driver-model/{of-plat.txt => of-plat.rst}      | 193 +++---
> >   doc/driver-model/{pci-info.txt => pci-info.rst}    |  21 +-
> >   .../{pmic-framework.txt => pmic-framework.rst}     | 131 ++--
> >   ...proc-framework.txt => remoteproc-framework.rst} | 181 ++---
> >   .../{serial-howto.txt => serial-howto.rst}         |  12 +-
> >   doc/driver-model/spi-howto.rst                     | 692 +++++++++++++++++++
> >   doc/driver-model/spi-howto.txt                     | 623 -----------------
> >   doc/driver-model/{usb-info.txt => usb-info.rst}    | 184 ++---
> >   doc/index.rst                                      |  69 +-
> >   72 files changed, 4903 insertions(+), 4279 deletions(-)
> >   delete mode 100644 doc/README.AX25
> >   delete mode 100644 doc/README.N1213
> >   delete mode 100644 doc/README.NDS32
> >   delete mode 100644 doc/README.ae350
> >   delete mode 100644 doc/README.at91
> >   delete mode 100644 doc/README.b4860qds
> >   delete mode 100644 doc/README.blackfin
> >   delete mode 100644 doc/README.m68k
> >   delete mode 100644 doc/README.qemu-mips
> >   delete mode 100644 doc/README.sh
> >   delete mode 100644 doc/README.sh7752evb
> >   delete mode 100644 doc/README.sh7753evb
> >   delete mode 100644 doc/README.sifive-fu540
> >   rename doc/{ => api}/efi.rst (100%)
> >   create mode 100644 doc/api/index.rst
> >   rename doc/{ => api}/linker_lists.rst (100%)
> >   rename doc/{ => api}/serial.rst (100%)
> >   rename doc/{README.ARC => arch/arc.rst} (96%)
> >   rename doc/{README.arm64 => arch/arm64.rst} (83%)
> >   create mode 100644 doc/arch/index.rst
> >   create mode 100644 doc/arch/m68k.rst
> >   rename doc/{README.mips => arch/mips.rst} (74%)
> >   create mode 100644 doc/arch/nds32.rst
> >   rename doc/{README.nios2 => arch/nios2.rst} (51%)
> >   rename board/sandbox/README.sandbox => doc/arch/sandbox.rst (76%)
> >   create mode 100644 doc/arch/sh.rst
> >   rename doc/{README.x86 => arch/x86.rst} (51%)
> >   rename doc/{README.xtensa => arch/xtensa.rst} (90%)
> >   rename doc/{README.ag101p => board/AndesTech/adp-ag101p.rst} (83%)
> >   create mode 100644 doc/board/AndesTech/ax25-ae350.rst
> >   create mode 100644 doc/board/atmel/at91ek.rst
> >   create mode 100644 doc/board/coreboot/coreboot.rst
> >   create mode 100644 doc/board/coreboot/index.rst
> >   create mode 100644 doc/board/emulation/index.rst
> >   rename doc/{README.qemu-arm => board/emulation/qemu-arm.rst} (80%)
> >   create mode 100644 doc/board/emulation/qemu-mips.rst
> >   rename doc/{README.qemu-riscv => board/emulation/qemu-riscv.rst} (82%)
> >   create mode 100644 doc/board/emulation/qemu-x86.rst
> >   create mode 100644 doc/board/freescale/b4860qds.rst
> >   create mode 100644 doc/board/google/chromebook_link.rst
> >   create mode 100644 doc/board/google/chromebook_samus.rst
> >   create mode 100644 doc/board/google/index.rst
> >   create mode 100644 doc/board/index.rst
> >   create mode 100644 doc/board/intel/bayleybay.rst
> >   create mode 100644 doc/board/intel/cherryhill.rst
> >   create mode 100644 doc/board/intel/cougarcanyon2.rst
> >   create mode 100644 doc/board/intel/crownbay.rst
> >   create mode 100644 doc/board/intel/edison.rst
> >   create mode 100644 doc/board/intel/galileo.rst
> >   create mode 100644 doc/board/intel/index.rst
> >   create mode 100644 doc/board/intel/minnowmax.rst
> >   create mode 100644 doc/board/renesas/sh7752evb.rst
> >   create mode 100644 doc/board/renesas/sh7753evb.rst
> >   create mode 100644 doc/board/sifive/fu540.rst
> >   rename doc/{README.zynq => board/xilinx/zynq.rst} (53%)
> >   rename doc/driver-model/{README.txt => design.rst} (64%)
> >   rename doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} (89%)
> >   create mode 100644 doc/driver-model/fs_firmware_loader.rst
> >   delete mode 100644 doc/driver-model/fs_firmware_loader.txt
> >   rename doc/driver-model/{i2c-howto.txt => i2c-howto.rst} (82%)
> >   create mode 100644 doc/driver-model/index.rst
> >   rename doc/driver-model/{livetree.txt => livetree.rst} (77%)
> >   rename doc/driver-model/{MIGRATION.txt => migration.rst} (84%)
> >   rename doc/driver-model/{of-plat.txt => of-plat.rst} (65%)
> >   rename doc/driver-model/{pci-info.txt => pci-info.rst} (95%)
> >   rename doc/driver-model/{pmic-framework.txt => pmic-framework.rst} (51%)
> >   rename doc/driver-model/{remoteproc-framework.txt => remoteproc-framework.rst} (50%)
> >   rename doc/driver-model/{serial-howto.txt => serial-howto.rst} (92%)
> >   create mode 100644 doc/driver-model/spi-howto.rst
> >   delete mode 100644 doc/driver-model/spi-howto.txt
> >   rename doc/driver-model/{usb-info.txt => usb-info.rst} (77%)
> >
>
> Hello Bin,
>
> current origin/master make htmldocs gives me the following warnings:
>
> reading sources... [100%] board/index
>
> ./cmd/efidebug.c:733: WARNING: Unexpected indentation.
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/AndesTech/index'
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/atmel/index'
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/freescale/index'
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/renesas/index'
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/sifive/index'
> /doc/board/index.rst:6: WARNING: toctree contains reference to
> nonexisting document 'board/xilinx/index'
> looking for now-outdated files... none found
> pickling environment... done
> checking consistency... /doc/board/AndesTech/adp-ag101p.rst: WARNING:
> document isn't included in any toctree
> /doc/board/AndesTech/ax25-ae350.rst: WARNING: document isn't included in
> any toctree
> /doc/board/atmel/at91ek.rst: WARNING: document isn't included in any toctree
> /doc/board/freescale/b4860qds.rst: WARNING: document isn't included in
> any toctree
> /doc/board/renesas/sh7752evb.rst: WARNING: document isn't included in
> any toctree
> /doc/board/renesas/sh7753evb.rst: WARNING: document isn't included in
> any toctree
> /doc/board/sifive/fu540.rst: WARNING: document isn't included in any toctree
> /doc/board/xilinx/zynq.rst: WARNING: document isn't included in any toctree
> done
>
> The efidebug.c one I will care about. Will you have a look at the
> others, please?

Thanks for reporting. It looks that I missed adding these index to
'git stage' area before committing. That's why it escaped during my
local testing.

Regards,
Bin