Re: [PATCH V4 8/8] doc: board: ti: Add BeaglePlay documentation

[Mattijs Korpershoek <mkorpershoek@baylibre.com>]

On mer., août 23, 2023 at 22:27, Nishanth Menon <nm@ti.com> wrote:

> On 21:01-20230823, Simon Glass wrote:
>> Hi Nishanth,
>> 
>> On Wed, 23 Aug 2023 at 18:18, Nishanth Menon <nm@ti.com> wrote:
>> >
>> > On 17:57-20230823, Simon Glass wrote:
>> > [...]
>> > > > This is how we have a common bit of rST for how to build N boards,
>> > > > without having to do a literal copy and paste N times.
>> > >
>> > > How about using this?
>> > >
>> > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
>> >
>> > I was not able to succeed with complex includes such as:
>> > https://github.com/u-boot/u-boot/blob/master/doc/board/ti/am62x_sk.rst?plain=1#L89
>> >
>> > am62x complete build procedure defined once and reused in other am62x
>> > platforms.. But the am62x build procedure itself is reused from common
>> > k3 build steps.
>> 
>> I followed through these instructions. I find the env vars quite
>> confusing, since I don't really know what it is doing. It feels like a
>> script:
>> 
>> do $a $b $c
>> do $f $e
>> 
>> it is pretty hard to follow. I think it would be better to write
>> everything out in full for each board, like rockchip does.
>
> Unfortunately, this is a few major steps that is repeated for
> (currently):
> 	AM62x SK
> 	Toradex Verdin
> 	(pending: beagleplay - )
> 	(once all the dust clears up, hopefully phytec)
> 	SK-LP
> 	....
>
> I have no reasonable way to offer to keep them all in sync.
> 	https://libera.irclog.whitequark.org/u-boot/2023-07-26#34662854;
> is kind of why I went down this path.S
>
>> 
>> Some other minor feedback:
>> 
>> - The 'make' lines should really have -j $(nproc) added
>
> Different styles of shells..
>
>> - The $ signs at the start of each command in the docs are a pain
>> since it stops me copying the commands into the terminal - can you
>> remove them?
>
> hehe.. "dont" let people blindly copy paste without understanding what is
> going on argument?
>
> If folks are OK, I sure can send a different patch series for that.. (or
> maybe motivate someone to do that instead of me ;))

Have we considered using the .. prompt:: extension ?

https://pypi.org/project/sphinx-prompt/

The prompt extension automatically adds a prompt (like $) in front of
each line and disallows copying it when copying from the html generated page.

>
>
>> - It doesn't build for me:
>> 
>>   BINMAN  .binman_stamp
>> Image 'ti-dm' is missing external blobs and is non-functional: blob-ext
>> 
>> /binman/ti-dm/blob-ext (ti-dm/am62xx/ipc_echo_testb_mcu1_0_release_strip.xer5f):
>>    Missing blob
>> 
>> Some images are invalid
>> make[1]: *** [/scratch/sglass/cosarm/src/third_party/u-boot/files/Makefile:1115:
>> .binman_stamp] Error 103
>> make[1]: Leaving directory '/tmp/b/play'
>> make: *** [Makefile:177: sub-make] Error 2
>
>
> ^^ Neha: This is what I was complaining about.
>
> https://u-boot.readthedocs.io/en/latest/board/ti/am62x_sk.html?highlight=am62#sources
>
> source: https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
> is missing, we never used to break build previously binman converted now does.
>
> I am wondering if I need to explicitly call out git clone instructions
> out..
>
> -- 
> Regards,
> Nishanth Menon
> Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D