Re: [RFC PATCH] docs/devel: re-organise the developers guide into sections

[Peter Maydell]

On Tue, 23 Feb 2021 at 10:51, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> The list of sub-sections was getting a bit long and sporadically
> organised. Let's try and impose some order on this hairball of
> documentation.

Yeah, the 'devel' section has always been just a grab-bag
of whatever docs we had to hand. On the other hand, to my
mind it is the area of the documentation that is least in
need of much effort, because it's only for developers, not
for the much wider group of end-users.

Anyways, a bit more structure certainly doesn't hurt.

> [AJB: RFC because I wonder if we should make a more concerted effort
> to move bits of the wiki into a canonical maintained document. There
> is also probably a need for a quickbuild or tldr section of the
> build-system for users who just want to build something.]

'How to build' is in README.rst. We don't want that in the devel/
section, because we describe 'devel' as "You only need to read it
if you are interested in reading or modifying QEMU’s source code".

> diff --git a/docs/devel/section-apis.rst b/docs/devel/section-apis.rst
> new file mode 100644
> index 0000000000..ab1f6bed60
> --- /dev/null
> +++ b/docs/devel/section-apis.rst
> @@ -0,0 +1,16 @@
> +*********
> +QEMU APIs
> +*********
> +
> +There are a number of APIs in QEMU and the following sections document
> +some of the most important ones. For tose that aren't documented here
> +you can also find notes on usage in the header definitions.

"those"

-- PMM