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

[Wainer dos Santos Moschetta <wainersm@redhat.com>]

Hi,

On 2/23/21 7:51 AM, Alex Bennée 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.
>
> [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.]
>
> Based-on: 20210223095931.16908-1-alex.bennee@linaro.org
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   docs/devel/index.rst                 | 32 ++++++----------------------
>   docs/devel/multi-thread-tcg.rst      |  5 +++--
>   docs/devel/section-apis.rst          | 16 ++++++++++++++
>   docs/devel/section-building.rst      | 13 +++++++++++
>   docs/devel/section-concepts.rst      | 21 ++++++++++++++++++
>   docs/devel/section-process.rst       | 11 ++++++++++
>   docs/devel/section-tcg-emulation.rst | 19 +++++++++++++++++
>   docs/devel/section-testing.rst       | 20 +++++++++++++++++
>   docs/devel/tcg-icount.rst            |  6 +++---
>   docs/devel/testing.rst               |  6 +++---
>   10 files changed, 115 insertions(+), 34 deletions(-)
>   create mode 100644 docs/devel/section-apis.rst
>   create mode 100644 docs/devel/section-building.rst
>   create mode 100644 docs/devel/section-concepts.rst
>   create mode 100644 docs/devel/section-process.rst
>   create mode 100644 docs/devel/section-tcg-emulation.rst
>   create mode 100644 docs/devel/section-testing.rst
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index ae664da00c..2af7bf8736 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -13,29 +13,9 @@ Contents:
>   .. toctree::
>      :maxdepth: 2
>   
> -   build-system
> -   style
> -   kconfig
> -   testing
> -   fuzzing
> -   control-flow-integrity
> -   loads-stores
> -   memory
> -   migration
> -   atomics
> -   stable-process
> -   qtest
> -   decodetree
> -   secure-coding-practices
> -   tcg
> -   tcg-icount
> -   tracing
> -   multi-thread-tcg
> -   tcg-plugins
> -   bitops
> -   reset
> -   s390-dasd-ipl
> -   clocks
> -   qom
> -   block-coroutine-wrapper
> -   multi-process
> +   section-building
> +   section-testing
> +   section-concepts
> +   section-apis
> +   section-tcg-emulation
> +   section-process

Just a fyi... yesterday I realized that the (current) TOC is not getting 
rendered on my Firefox (or chrome) browser:

https://gitlab.com/qemu-project/qemu/-/tree/master/docs/devel

- Wainer

> diff --git a/docs/devel/multi-thread-tcg.rst b/docs/devel/multi-thread-tcg.rst
> index 92a9eba13c..5b446ee08b 100644
> --- a/docs/devel/multi-thread-tcg.rst
> +++ b/docs/devel/multi-thread-tcg.rst
> @@ -4,8 +4,9 @@
>     This work is licensed under the terms of the GNU GPL, version 2 or
>     later. See the COPYING file in the top-level directory.
>   
> -Introduction
> -============
> +==================
> +Multi-threaded TCG
> +==================
>   
>   This document outlines the design for multi-threaded TCG (a.k.a MTTCG)
>   system-mode emulation. user-mode emulation has always mirrored the
> 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.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   atomics
> +   bitops
> +   loads-stores
> +   memory
> +   tracing
> diff --git a/docs/devel/section-building.rst b/docs/devel/section-building.rst
> new file mode 100644
> index 0000000000..e6e9fa1d6a
> --- /dev/null
> +++ b/docs/devel/section-building.rst
> @@ -0,0 +1,13 @@
> +*************
> +Building QEMU
> +*************
> +
> +The following sections deal with how the build system works, how it is
> +configured and some basic guidance on how code should be written.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   build-system
> +   kconfig
> +   style
> diff --git a/docs/devel/section-concepts.rst b/docs/devel/section-concepts.rst
> new file mode 100644
> index 0000000000..566c52e90a
> --- /dev/null
> +++ b/docs/devel/section-concepts.rst
> @@ -0,0 +1,21 @@
> +*************
> +QEMU Concepts
> +*************
> +
> +There are a number of high level concepts that are useful to
> +understand when working with the code base. Perhaps the most pervasive
> +is the QEMU Object Model (QOM) which underpins much of the flexibility
> +and configurable of the project. The following sections document that
> +as well as diving into other concepts that are useful to know if
> +working on some areas of the code.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   qom
> +   clocks
> +   reset
> +   block-coroutine-wrapper
> +   migration
> +   multi-process
> +   s390-dasd-ipl
> diff --git a/docs/devel/section-process.rst b/docs/devel/section-process.rst
> new file mode 100644
> index 0000000000..3b0ae4f19b
> --- /dev/null
> +++ b/docs/devel/section-process.rst
> @@ -0,0 +1,11 @@
> +===================
> +Development Process
> +===================
> +
> +The following sections detail aspects of the development process.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   secure-coding-practices
> +   stable-process
> diff --git a/docs/devel/section-tcg-emulation.rst b/docs/devel/section-tcg-emulation.rst
> new file mode 100644
> index 0000000000..81fa131de7
> --- /dev/null
> +++ b/docs/devel/section-tcg-emulation.rst
> @@ -0,0 +1,19 @@
> +*************
> +TCG Emulation
> +*************
> +
> +QEMU was originally built as an emulator capable of running binaries
> +for one architecture on another. The following sections describe the
> +internals of how the Just In Time (JIT) Tiny Code Generator (TCG)
> +works. You only really need to read this if you are interested in
> +adding new architectures or fixing existing architecture emulation.
> +
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   tcg
> +   multi-thread-tcg
> +   tcg-icount
> +   decodetree
> +   tcg-plugins
> diff --git a/docs/devel/section-testing.rst b/docs/devel/section-testing.rst
> new file mode 100644
> index 0000000000..c93ff4c4dd
> --- /dev/null
> +++ b/docs/devel/section-testing.rst
> @@ -0,0 +1,20 @@
> +***************
> +Testing in QEMU
> +***************
> +
> +QEMU is a large and complex project which can be configured in a
> +multitude of ways. As it's impossible for an individual developer to
> +manually test all of these we rely on a whole suite of automated
> +testing approaches to ensure regressions are kept to a minimum.
> +
> +The following sections give a broad overview of the testing
> +infrastructure as well as some detailed introductions into more
> +advanced testing topics.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   testing
> +   fuzzing
> +   control-flow-integrity
> +   qtest
> diff --git a/docs/devel/tcg-icount.rst b/docs/devel/tcg-icount.rst
> index 8d67b6c076..eb990b0976 100644
> --- a/docs/devel/tcg-icount.rst
> +++ b/docs/devel/tcg-icount.rst
> @@ -3,9 +3,9 @@
>      Written by Alex Bennée
>   
>   
> -========================
> -TCG Instruction Counting
> -========================
> +=================================
> +TCG Instruction Counting (icount)
> +=================================
>   
>   TCG has long supported a feature known as icount which allows for
>   instruction counting during execution. This should not be confused
> diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
> index 3124ee2470..a69db8ab93 100644
> --- a/docs/devel/testing.rst
> +++ b/docs/devel/testing.rst
> @@ -1,6 +1,6 @@
> -===============
> -Testing in QEMU
> -===============
> +=======
> +Testing
> +=======
>   
>   This document describes the testing infrastructure in QEMU.
>