[U-Boot] [PATCH 00/50] doc: Shape into useful HTML docs

Heinrich Schuchardt xypron.glpk at gmx.de
Thu Jul 25 18:31:58 UTC 2019


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


More information about the U-Boot mailing list