Re: [PATCH 0/5] docs/system: Document some arm board models

["Philippe Mathieu-Daudé" <philmd@redhat.com>]

On 5/15/20 10:51 AM, Peter Maydell wrote:
> On Fri, 15 May 2020 at 09:03, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>> However I'd rather see the board documentation in the source code, and
>> extract it when building. It'd be harder to miss updating the
>> documentation when modifying the code.
> 
> I definitely agree in principle; but for the moment at least
> we can have some documentation...

Yes, thank you very much for this effort!

> 
>> Another way (rather than using external program to extract from source
>> code) can be to add a method/field to MachineClass, and once a build is
>> finished, we could run 'qemu-system-arch -M gendoc' which go thru all
>> machines and display the documentation properly formatted.
> 
> The documentation needs to include all machines, not just
> the ones that got compiled into a particular binary, so
> I'm not sure this will work. I also would prefer it if
> we avoided having the docs build depend on doing a full
> binary build -- places like readthedocs will just do a docs
> build by invoking Sphinx directly, and we'd like the machine
> docs to be visible there.

Sphinx consumes docs/system/$arch/$machine.rst files committed to the 
repository, and we don't need to build various qemu-system-arch to 
generate the documentation.

If you work on a particular board, you might end up only building its 
corresponding qemu-system-ARCH. Maybe we can add an extra-pass once a 
binary is linked, and re-generate the docs/system/ARCH/$machine.rst 
files, so if you modified a board and its documentation placeholder in 
the code, when commiting your code change, you also have to commit the 
rst changes.

Just brainstorming an idea for now ;)

> 
> thanks
> -- PMM
>