[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