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
_______________________________________________
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

Reply via email to