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