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

[Heinrich Schuchardt]

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/

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

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

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.

Best regards

Heinrich

>
> See the commit message for why I chose this. I suppose I could add a
> separate README if needed.
>
> Regards,
> Simon
>