Message ID | 1563435275-22326-1-git-send-email-bmeng.cn@gmail.com |
---|---|
Headers | show |
Series | doc: Shape into useful HTML docs | expand |
Hi Tom, On Thu, Jul 18, 2019 at 3:34 PM Bin Meng <bmeng.cn@gmail.com> 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. > Ping? Regards, Bin
Dear Bin, In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote: > > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de? > > > > This series is available at u-boot-x86/doc for testing. > > > > Ping? Yes, this is possible. Where can I find the HTML files? And where would you want to put them? And what is the planned update strategy? I mean, plain HTML documents are a bit lame, as they refer to a specific version of U-Boot only. What if I want to see the docs for a version of half a year ago? What exactly are your plans? Best regards, Wolfgang Denk
On Tue, Jul 23, 2019 at 05:00:52PM +0200, Wolfgang Denk wrote: > Dear Bin, > > In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote: > > > > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de? > > > > > > This series is available at u-boot-x86/doc for testing. > > > > > > > Ping? > > Yes, this is possible. Where can I find the HTML files? And where > would you want to put them? And what is the planned update > strategy? > > I mean, plain HTML documents are a bit lame, as they refer to a > specific version of U-Boot only. What if I want to see the docs for > a version of half a year ago? Thinking out loud, how about .../<VERSION>/ and we re-generate the docs for each full release?
Hi Wolfgang, On Tue, Jul 23, 2019 at 11:01 PM Wolfgang Denk <wd@denx.de> wrote: > > Dear Bin, > > In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote: > > > > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de? > > > > > > This series is available at u-boot-x86/doc for testing. > > > > > > > Ping? > > Yes, this is possible. Where can I find the HTML files? And where The HTML files can be generated from the U-Boot source tree by "make htmldocs". > would you want to put them? And what is the planned update > strategy? If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs? > > I mean, plain HTML documents are a bit lame, as they refer to a > specific version of U-Boot only. What if I want to see the docs for > a version of half a year ago? > > What exactly are your plans? For versioned HTML, let's take a look at how Linux kernel does: https://www.kernel.org/doc/html/ I think we can imitate Linux by having released doc archive (generated for each release), latest doc which is nightly built that always points to latest htmldocs in the tree. Maybe we can have additional -rc release doc for current release (eg: v2019.10-rc1), and these -rc htmldocs will get cleaned up when the official release is out. Thoughts? Regards, Bin
Hi Tom, On Tue, Jul 23, 2019 at 11:29 PM Tom Rini <trini@konsulko.com> wrote: > > On Tue, Jul 23, 2019 at 05:00:52PM +0200, Wolfgang Denk wrote: > > Dear Bin, > > > > In message <CAEUhbmVBz0z+Dh_q1hJKDOuoiJ1ZJ025hiLrYFUwDbp0UrxD1g@mail.gmail.com> you wrote: > > > > > > > @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de? > > > > > > > > This series is available at u-boot-x86/doc for testing. > > > > > > > > > > Ping? > > > > Yes, this is possible. Where can I find the HTML files? And where > > would you want to put them? And what is the planned update > > strategy? > > > > I mean, plain HTML documents are a bit lame, as they refer to a > > specific version of U-Boot only. What if I want to see the docs for > > a version of half a year ago? > > Thinking out loud, how about .../<VERSION>/ and we re-generate the docs > for each full release? If I understand correctly, you were proposing exact the same thing as I thought, so something like: http://denx.de/u-boot/doc/html/v2018.07/ http://denx.de/u-boot/doc/html/v2019.10-rc1/ http://denx.de/u-boot/doc/html/latest/ Anyway these are doc update strategy and has nothing to do with the patch series itself. If no issues, could you please apply them? I am afraid the longer time it sits in the patch queue, the possibility of merge conflicts happen. Regards, Bin
Dear Bin, In message <CAEUhbmXhLPkyiBaMxUgjZ_dyJna_ws63WspGQuzNCtGmjqAZwQ@mail.gmail.com> you wrote: > > The HTML files can be generated from the U-Boot source tree by "make htmldocs". > > > would you want to put them? And what is the planned update > > strategy? > > If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs? I had hoped for a bit more specific ideas. Where _exactly_ would you want to see them? Speaking for myself, I would search for them under http://www.denx.de/wiki/U-Boot/Documentation ? > For versioned HTML, let's take a look at how Linux kernel does: > https://www.kernel.org/doc/html/ OK, we can copy that. Best regards, Wolfgang Denk
Hi Wolfgang, On Wed, Jul 24, 2019 at 3:08 PM Wolfgang Denk <wd@denx.de> wrote: > > Dear Bin, > > In message <CAEUhbmXhLPkyiBaMxUgjZ_dyJna_ws63WspGQuzNCtGmjqAZwQ@mail.gmail.com> you wrote: > > > > The HTML files can be generated from the U-Boot source tree by "make htmldocs". > > > > > would you want to put them? And what is the planned update > > > strategy? > > > > If possible, can we have denx.de or gitlab.denx.de host the generated HTML docs? > > I had hoped for a bit more specific ideas. Where _exactly_ would you > want to see them? > > Speaking for myself, I would search for them under > http://www.denx.de/wiki/U-Boot/Documentation > > ? Sorry if I was not clear enough. Since I am not entirely sure about the denx.de website layout I only say some rough ideas. The new Sphinx htmldoc will have an index.html that can be hooked into a URL. > > > For versioned HTML, let's take a look at how Linux kernel does: > > https://www.kernel.org/doc/html/ > > OK, we can copy that. I assume you already got my idea :) Regards, Bin
On Thu, Jul 18, 2019 at 12:33:45AM -0700, 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. As a follow-up, please update .gitlab-ci.yml at least to include a run of "make htmldocs". If we need to update the Dockerfile to include new utils we can do that too, thanks!
Hi Tom, On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote: > > On Thu, Jul 18, 2019 at 12:33:45AM -0700, 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. > > As a follow-up, please update .gitlab-ci.yml at least to include a run > of "make htmldocs". If we need to update the Dockerfile to include new > utils we can do that too, thanks! Yes, but I will need some time to study GitLab's .gitlab-ci.yml :) Could that be done later? Regards, Bin
On Wed, Jul 24, 2019 at 10:16:31PM +0800, Bin Meng wrote: > Hi Tom, > > On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote: > > > > On Thu, Jul 18, 2019 at 12:33:45AM -0700, 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. > > > > As a follow-up, please update .gitlab-ci.yml at least to include a run > > of "make htmldocs". If we need to update the Dockerfile to include new > > utils we can do that too, thanks! > > Yes, but I will need some time to study GitLab's .gitlab-ci.yml :) > > Could that be done later? Yes, to be clear, I asked for a follow-up as I have this otherwise merged locally but can't test it since make htmldocs blows up about a lack of required tools that I don't see documented. Once my current pipeline finishes (of other changes) I'll push this.
On 7/24/19 4:18 PM, Tom Rini wrote: > On Wed, Jul 24, 2019 at 10:16:31PM +0800, Bin Meng wrote: >> Hi Tom, >> >> On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote: >>> >>> On Thu, Jul 18, 2019 at 12:33:45AM -0700, 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. >>> >>> As a follow-up, please update .gitlab-ci.yml at least to include a run >>> of "make htmldocs". If we need to update the Dockerfile to include new >>> utils we can do that too, thanks! >> >> Yes, but I will need some time to study GitLab's .gitlab-ci.yml :) >> >> Could that be done later? > > Yes, to be clear, I asked for a follow-up as I have this otherwise > merged locally but can't test it since make htmldocs blows up about a > lack of required tools that I don't see documented. Once my current > pipeline finishes (of other changes) I'll push this. > Hello Tom, the necessary packages for Ubuntu Bionic to run 'make htmldocs' are: build-essential sphinx-doc python3-sphinx A warning occurs requesting packages graphviz and imagemagick. Graphviz is currently not installable via apt-get but as we currently have no graphics in our documentation you can simply ignore the warnings. Cf. https://www.katrinasiegfried.com/single-post/2018/10/24/Installing-GraphViz-on-Linux-Ubuntu-1804LTS The ReadTheDocs theme can be installed via git clone https://github.com/readthedocs/sphinx_rtd_theme cd sphinx_rtd_theme/ sudo apt-get install python3-setuptools python3 setup.py install This theme is not really needed but the output looks much nicer. The generated documentation is available under doc/output/. Best regards Heinrich
On Thu, Jul 18, 2019 at 12:33:45AM -0700, 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 For the series, applied to u-boot/master, thanks!
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
Hi Heinrich, On Fri, Jul 26, 2019 at 2:32 AM Heinrich Schuchardt <xypron.glpk@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