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

[Heinrich Schuchardt]

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/

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

Best regards

Heinrich

>
> Regards,
> Simon
>