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

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

[Alex Bennée]

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
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.
 
-- 
2.20.1

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

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1654 bytes --]

On Tue, Feb 23, 2021 at 10:51:46AM +0000, 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

Acked-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Wainer dos Santos Moschetta]

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.
>   

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

[Peter Maydell]

On Wed, 24 Feb 2021 at 12:51, Wainer dos Santos Moschetta
<wainersm@redhat.com> wrote:
> 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

That's the source code for the docs, isn't it? gitlab
is trying to render it as raw rst, but that won't handle
all the Sphinx-specific markup, including the TOC.

The built-and-rendered docs are elsewhere (the gitlab CI
job runs Sphinx and puts the rendered manuals here):
https://qemu-project.gitlab.io/qemu/

thanks
-- PMM

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

[Wainer dos Santos Moschetta]

On 2/24/21 10:15 AM, Peter Maydell wrote:
> On Wed, 24 Feb 2021 at 12:51, Wainer dos Santos Moschetta
> <wainersm@redhat.com> wrote:
>> 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
> That's the source code for the docs, isn't it? gitlab
> is trying to render it as raw rst, but that won't handle
> all the Sphinx-specific markup, including the TOC.
You're right Peter. For one second I thought gitlab was able to render 
the rst files.
>
> The built-and-rendered docs are elsewhere (the gitlab CI
> job runs Sphinx and puts the rendered manuals here):
> https://qemu-project.gitlab.io/qemu/
>
> thanks
> -- PMM
>