[PATCH 16/20] binman: doc: Add documentation to htmldocs

[Simon Glass]

Hi Heinrich,

On Sun, 7 Mar 2021 at 17:31, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> On 3/7/21 11:17 PM, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Sun, 7 Mar 2021 at 17:13, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
> >>
> >> On 3/7/21 10:22 PM, Simon Glass wrote:
> >>> Hi Heinrich,
> >>>
> >>> On Sun, 7 Mar 2021 at 15:02, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
> >>>>
> >>>> On 3/7/21 8:31 PM, Simon Glass wrote:
> >>>>> Add a link to binman's documentation and adjust the files so that it is
> >>>>> accessible. Use the name README.rst so it is easy to discover when binman
> >>>>> is installed without U-Boot.
> >>>>>
> >>>>> Signed-off-by: Simon Glass <sjg at chromium.org>
> >>>>> ---
> >>>>>
> >>>>>     doc/index.rst                       |   1 +
> >>>>>     doc/package/binman                  |   1 +
> >>>>>     doc/package/fit.rst                 |   8 +
> >>>>
> >>>> This information is only of interest for developers, not for end-users.
> >>>> Please, place that information in /doc/develop/.
> >>>
> >>> What is the difference between this and building? The build stuff is
> >>> at the top level. People presumably need to package U-Boot as well, in
> >>> order to use it.
> >>
> >> I never needed to use binman directly to build U-Boot and deploy it.
> >> That is why I say it should be described in /doc/develop/
> >>
> >> FIT images to containing a kernel are a different story. Those should be
> >> described in /doc/usage/
> >
> > OK well I'll put it under develop.
> >
> >>
> >>>
> >>>>
> >>>>>     doc/package/index.rst               |  20 ++
> >>>>>     tools/binman/{README => README.rst} | 480 ++++++++++++++--------------
> >>>>
> >>>> tools/binman/ is the wrong path for documentation. Please, put the file
> >>>> in /doc/develop/binman.rst or /doc/develop/tools/binman.rst so that it
> >>>> becomes available online.
> >>>
> >>> Does this mean that README.rst would not appear? Why not?
> >>
> >> All documentation should reside in doc
> >> --------------------------------------
> >>
> >> You added a symbolic link
> >>
> >>      doc/package/binman=>../../tools/binman
> >>
> >> including a whole bunch of unrelated files into doc.
> >>
> >> To me this is chaos. I want to have one directory with all documentation.
> >>
> >> A filename called README.rst does not convey what it is about. So it is
> >> unsuitable inside doc/
> >>
> >> Binman is useless outside U-Boot as it needs the board device-trees
> >> coming with U-Boot. There is no reason to install it without U-Boot.
> >
> > Actually it doesn't. We are using it with Zephyr, for example. I do
>
> The README says it uses the board device-trees. But I guess you know
> better where it could be used.
>
> Zephyr test management?
> https://www.getzephyr.com/
>
> Zephyr RTOS?
> https://www.zephyrproject.org/

That one.

>
> > want to support installing it on a system, just like patman.
> >
> >>
> >> The patch creates a bug
> >> -----------------------
> >>
> >> $ tools/binman/binman -H
> >> more: cannot open tools/binman/README: No such file or directory
> >>
> >> The patch is not applicable to origin/master
> >
> > It is based on us/next....the background here is that a whole load of
> > patches got punted to -next so everything I am doing now is on -next.
> >
> >
> >> --------------------------------------------
> >>
> >> Applying: binman: doc: Add documentation to htmldocs
> >> error: patch failed: tools/binman/README:844
> >> error: tools/binman/README: patch does not apply
> >>
> >> doc/package/binman/README.rst does not build
> >> --------------------------------------------
> >>
> >> Warning, treated as error:
> >> doc/package/binman/README.rst:851:Definition list ends without a blank
> >> line; unexpected unindent.
> >>
> >> So I suggest that you put a binman.rst into /doc/devel and fix binman to
> >> find its documentation.
> >
> > I cannot simply copy the docs into that directory. Then we end up with
> > two copies. What exactly is wrong with a symlink?
>
> If you want to symlink, please, only symlink the single file and not the
> directory and in /doc call it binman.rst.

OK I can symlink each file individually.

Regards,
Simon