[U-Boot] [PATCH 00/50] doc: Shape into useful HTML docs
Bin Meng
bmeng.cn at gmail.com
Fri Jul 26 01:54:55 UTC 2019
Hi Heinrich,
On Fri, Jul 26, 2019 at 2:32 AM Heinrich Schuchardt <xypron.glpk at 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
More information about the U-Boot
mailing list