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

[Philippe Mathieu-Daudé]

On 5/15/20 10:51 AM, Peter Maydell wrote:
> On Fri, 15 May 2020 at 09:03, Philippe Mathieu-Daudé <address@hidden> 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