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

[Peter Maydell <peter.maydell@linaro.org>]

On Fri, 15 May 2020 at 10:05, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
> 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.

I'm not a huge fan of committing generated files to source control...
I think I'd prefer an approach that worked via some kind of
kerneldoc comments that we pull out and parse using the Sphinx
plugin we have for that. (There's more complication than that
but roughly I think that would be the kind of approach I'd like
to see.)

thanks
-- PMM