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

[Simon Glass]

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
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?

Regards,
Simon