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

Bin Meng bmeng.cn at gmail.com
Thu Jul 18 07:33:45 UTC 2019


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%)

-- 
2.7.4



More information about the U-Boot mailing list