[PATCH v2 0/7] docs/devel: Organize devel manual into further subsections

[PATCH v2 0/7] docs/devel: Organize devel manual into further subsections

[John Snow]

It's a bit cluttered. On my way to converting the QAPI/QMP documents to
ReST I thought it could do with another organizational level to help
make sense of things a bit more quickly.

V2:
 - Move decodetree into TCG subsection
 - Rebase, add QOM/QAPI/QMP docs into API subsection

John Snow (7):
  docs/devel: create "Community & Governance" subsection
  docs/devel: create "Developing QEMU" subsection
  docs/devel: create "Testing & Debugging" subsection
  docs/devel: create TCG subsection
  docs/devel: create "Subsystem APIs" subsection
  docs/devel: create "QEMU API" section
  docs/devel: create "Miscellaneous Topics" subsection

 docs/devel/index.rst                        | 42 ++++-----------------
 docs/devel/section-api.rst                  | 10 +++++
 docs/devel/section-community-governance.rst |  9 +++++
 docs/devel/section-development.rst          | 12 ++++++
 docs/devel/section-misc.rst                 | 13 +++++++
 docs/devel/section-subsystems.rst           | 16 ++++++++
 docs/devel/section-tcg.rst                  | 12 ++++++
 docs/devel/section-testing-debugging.rst    | 12 ++++++
 8 files changed, 91 insertions(+), 35 deletions(-)
 create mode 100644 docs/devel/section-api.rst
 create mode 100644 docs/devel/section-community-governance.rst
 create mode 100644 docs/devel/section-development.rst
 create mode 100644 docs/devel/section-misc.rst
 create mode 100644 docs/devel/section-subsystems.rst
 create mode 100644 docs/devel/section-tcg.rst
 create mode 100644 docs/devel/section-testing-debugging.rst

-- 
2.31.1

[PATCH v2 1/7] docs/devel: create "Community & Governance" subsection

[John Snow]

Plonk the Code of Conduct and Conflict Resolution Policy guides into a
new "Community & Governance" subsection.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst                        | 3 +--
 docs/devel/section-community-governance.rst | 9 +++++++++
 2 files changed, 10 insertions(+), 2 deletions(-)
 create mode 100644 docs/devel/section-community-governance.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 5522db72411..008d489d751 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -9,8 +9,7 @@ modifying QEMU's source code.
    :maxdepth: 2
    :includehidden:
 
-   code-of-conduct
-   conflict-resolution
+   section-community-governance
    build-system
    style
    kconfig
diff --git a/docs/devel/section-community-governance.rst b/docs/devel/section-community-governance.rst
new file mode 100644
index 00000000000..2c7e07257d1
--- /dev/null
+++ b/docs/devel/section-community-governance.rst
@@ -0,0 +1,9 @@
+Community & Governance
+======================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   code-of-conduct
+   conflict-resolution
-- 
2.31.1

[PATCH v2 2/7] docs/devel: create "Developing QEMU" subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst               |  6 +-----
 docs/devel/section-development.rst | 12 ++++++++++++
 2 files changed, 13 insertions(+), 5 deletions(-)
 create mode 100644 docs/devel/section-development.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 008d489d751..57016edd841 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -10,9 +10,7 @@ modifying QEMU's source code.
    :includehidden:
 
    section-community-governance
-   build-system
-   style
-   kconfig
+   section-development
    testing
    fuzzing
    control-flow-integrity
@@ -20,11 +18,9 @@ modifying QEMU's source code.
    memory
    migration
    atomics
-   stable-process
    ci
    qtest
    decodetree
-   secure-coding-practices
    tcg
    tcg-icount
    tracing
diff --git a/docs/devel/section-development.rst b/docs/devel/section-development.rst
new file mode 100644
index 00000000000..bba4fea30cb
--- /dev/null
+++ b/docs/devel/section-development.rst
@@ -0,0 +1,12 @@
+Developing QEMU
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   build-system
+   kconfig
+   style
+   secure-coding-practices
+   stable-process
-- 
2.31.1

[PATCH v2 3/7] docs/devel: create "Testing & Debugging" subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst                     |  6 +-----
 docs/devel/section-testing-debugging.rst | 12 ++++++++++++
 2 files changed, 13 insertions(+), 5 deletions(-)
 create mode 100644 docs/devel/section-testing-debugging.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 57016edd841..41fb32e922e 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -11,19 +11,15 @@ modifying QEMU's source code.
 
    section-community-governance
    section-development
-   testing
-   fuzzing
+   section-testing-debugging
    control-flow-integrity
    loads-stores
    memory
    migration
    atomics
-   ci
-   qtest
    decodetree
    tcg
    tcg-icount
-   tracing
    multi-thread-tcg
    tcg-plugins
    bitops
diff --git a/docs/devel/section-testing-debugging.rst b/docs/devel/section-testing-debugging.rst
new file mode 100644
index 00000000000..e59ddab4cf5
--- /dev/null
+++ b/docs/devel/section-testing-debugging.rst
@@ -0,0 +1,12 @@
+Testing & Debugging
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   ci
+   fuzzing
+   qtest
+   testing
+   tracing
-- 
2.31.1

[PATCH v2 4/7] docs/devel: create TCG subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst       |  6 +-----
 docs/devel/section-tcg.rst | 12 ++++++++++++
 2 files changed, 13 insertions(+), 5 deletions(-)
 create mode 100644 docs/devel/section-tcg.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 41fb32e922e..84bdd10abcb 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -12,16 +12,12 @@ modifying QEMU's source code.
    section-community-governance
    section-development
    section-testing-debugging
+   section-tcg
    control-flow-integrity
    loads-stores
    memory
    migration
    atomics
-   decodetree
-   tcg
-   tcg-icount
-   multi-thread-tcg
-   tcg-plugins
    bitops
    ui
    reset
diff --git a/docs/devel/section-tcg.rst b/docs/devel/section-tcg.rst
new file mode 100644
index 00000000000..dec4ab984b6
--- /dev/null
+++ b/docs/devel/section-tcg.rst
@@ -0,0 +1,12 @@
+TCG - Tiny Code Generator
+=========================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   tcg
+   tcg-icount
+   multi-thread-tcg
+   decodetree
+   tcg-plugins
-- 
2.31.1

[PATCH v2 5/7] docs/devel: create "Subsystem APIs" subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst              | 10 +---------
 docs/devel/section-subsystems.rst | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 9 deletions(-)
 create mode 100644 docs/devel/section-subsystems.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 84bdd10abcb..b146ce00f7a 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -13,18 +13,10 @@ modifying QEMU's source code.
    section-development
    section-testing-debugging
    section-tcg
+   section-subsystems
    control-flow-integrity
-   loads-stores
-   memory
-   migration
-   atomics
-   bitops
-   ui
-   reset
    s390-dasd-ipl
-   clocks
    qom
-   modules
    block-coroutine-wrapper
    multi-process
    ebpf_rss
diff --git a/docs/devel/section-subsystems.rst b/docs/devel/section-subsystems.rst
new file mode 100644
index 00000000000..fbe21f85adf
--- /dev/null
+++ b/docs/devel/section-subsystems.rst
@@ -0,0 +1,16 @@
+Subsystem APIs
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   atomics
+   bitops
+   loads-stores
+   clocks
+   memory
+   ui
+   migration
+   reset
+   modules
-- 
2.31.1

[PATCH v2 6/7] docs/devel: create "QEMU API" section

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/devel/index.rst       |  4 +---
 docs/devel/section-api.rst | 10 ++++++++++
 2 files changed, 11 insertions(+), 3 deletions(-)
 create mode 100644 docs/devel/section-api.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index b146ce00f7a..9f9e96204fc 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -12,14 +12,12 @@ modifying QEMU's source code.
    section-community-governance
    section-development
    section-testing-debugging
+   section-api
    section-tcg
    section-subsystems
    control-flow-integrity
    s390-dasd-ipl
-   qom
    block-coroutine-wrapper
    multi-process
    ebpf_rss
    vfio-migration
-   qapi-code-gen
-   writing-qmp-commands
diff --git a/docs/devel/section-api.rst b/docs/devel/section-api.rst
new file mode 100644
index 00000000000..d62b614fe3d
--- /dev/null
+++ b/docs/devel/section-api.rst
@@ -0,0 +1,10 @@
+QEMU API
+========
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   qapi-code-gen
+   writing-qmp-commands
+   qom
-- 
2.31.1

[PATCH v2 7/7] docs/devel: create "Miscellaneous Topics" subsection

[John Snow]

The hallmark of any truly great taxonomical reorganization: the bin of
leftover bits and pieces that didn't neatly fit elsewhere.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst        |  7 +------
 docs/devel/section-misc.rst | 13 +++++++++++++
 2 files changed, 14 insertions(+), 6 deletions(-)
 create mode 100644 docs/devel/section-misc.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 9f9e96204fc..3d86b4b5685 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -15,9 +15,4 @@ modifying QEMU's source code.
    section-api
    section-tcg
    section-subsystems
-   control-flow-integrity
-   s390-dasd-ipl
-   block-coroutine-wrapper
-   multi-process
-   ebpf_rss
-   vfio-migration
+   section-misc
diff --git a/docs/devel/section-misc.rst b/docs/devel/section-misc.rst
new file mode 100644
index 00000000000..e663e0e8b14
--- /dev/null
+++ b/docs/devel/section-misc.rst
@@ -0,0 +1,13 @@
+Miscellaneous Topics
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   control-flow-integrity
+   s390-dasd-ipl
+   block-coroutine-wrapper
+   multi-process
+   ebpf_rss
+   vfio-migration
-- 
2.31.1

Re: [PATCH v2 6/7] docs/devel: create "QEMU API" section

[Peter Maydell]

On Fri, 6 Aug 2021 at 16:51, John Snow <jsnow@redhat.com> wrote:
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/devel/index.rst       |  4 +---
>  docs/devel/section-api.rst | 10 ++++++++++
>  2 files changed, 11 insertions(+), 3 deletions(-)
>  create mode 100644 docs/devel/section-api.rst
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index b146ce00f7a..9f9e96204fc 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -12,14 +12,12 @@ modifying QEMU's source code.
>     section-community-governance
>     section-development
>     section-testing-debugging
> +   section-api
>     section-tcg
>     section-subsystems
>     control-flow-integrity
>     s390-dasd-ipl
> -   qom
>     block-coroutine-wrapper
>     multi-process
>     ebpf_rss
>     vfio-migration
> -   qapi-code-gen
> -   writing-qmp-commands
> diff --git a/docs/devel/section-api.rst b/docs/devel/section-api.rst
> new file mode 100644
> index 00000000000..d62b614fe3d
> --- /dev/null
> +++ b/docs/devel/section-api.rst
> @@ -0,0 +1,10 @@
> +QEMU API
> +========
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :includehidden:
> +
> +   qapi-code-gen
> +   writing-qmp-commands
> +   qom
> --
> 2.31.1


Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH v2 2/7] docs/devel: create "Developing QEMU" subsection

[Philippe Mathieu-Daudé]

On 8/6/21 5:51 PM, John Snow wrote:
> Signed-off-by: John Snow <jsnow@redhat.com>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/devel/index.rst               |  6 +-----
>  docs/devel/section-development.rst | 12 ++++++++++++
>  2 files changed, 13 insertions(+), 5 deletions(-)
>  create mode 100644 docs/devel/section-development.rst
> 
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index 008d489d751..57016edd841 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -10,9 +10,7 @@ modifying QEMU's source code.
>     :includehidden:
>  
>     section-community-governance
> -   build-system
> -   style
> -   kconfig
> +   section-development
>     testing
>     fuzzing
>     control-flow-integrity
> @@ -20,11 +18,9 @@ modifying QEMU's source code.
>     memory
>     migration
>     atomics
> -   stable-process
>     ci
>     qtest
>     decodetree
> -   secure-coding-practices
>     tcg
>     tcg-icount
>     tracing
> diff --git a/docs/devel/section-development.rst b/docs/devel/section-development.rst
> new file mode 100644
> index 00000000000..bba4fea30cb
> --- /dev/null
> +++ b/docs/devel/section-development.rst
> @@ -0,0 +1,12 @@
> +Developing QEMU
> +===============
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :includehidden:
> +

Could we order from generic to specific?

> +   style
> +   secure-coding-practices

> +   stable-process
> +   build-system
> +   kconfig
> 

Re: [PATCH v2 2/7] docs/devel: create "Developing QEMU" subsection

[Philippe Mathieu-Daudé]

On 8/6/21 6:40 PM, Philippe Mathieu-Daudé wrote:
> On 8/6/21 5:51 PM, John Snow wrote:
>> Signed-off-by: John Snow <jsnow@redhat.com>
>> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
>> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
>> ---
>>  docs/devel/index.rst               |  6 +-----
>>  docs/devel/section-development.rst | 12 ++++++++++++
>>  2 files changed, 13 insertions(+), 5 deletions(-)
>>  create mode 100644 docs/devel/section-development.rst
>>
>> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
>> index 008d489d751..57016edd841 100644
>> --- a/docs/devel/index.rst
>> +++ b/docs/devel/index.rst
>> @@ -10,9 +10,7 @@ modifying QEMU's source code.
>>     :includehidden:
>>  
>>     section-community-governance
>> -   build-system
>> -   style
>> -   kconfig
>> +   section-development
>>     testing
>>     fuzzing
>>     control-flow-integrity
>> @@ -20,11 +18,9 @@ modifying QEMU's source code.
>>     memory
>>     migration
>>     atomics
>> -   stable-process
>>     ci
>>     qtest
>>     decodetree
>> -   secure-coding-practices
>>     tcg
>>     tcg-icount
>>     tracing
>> diff --git a/docs/devel/section-development.rst b/docs/devel/section-development.rst
>> new file mode 100644
>> index 00000000000..bba4fea30cb
>> --- /dev/null
>> +++ b/docs/devel/section-development.rst
>> @@ -0,0 +1,12 @@
>> +Developing QEMU
>> +===============
>> +
>> +.. toctree::
>> +   :maxdepth: 2
>> +   :includehidden:
>> +
> 
> Could we order from generic to specific?

Oh this is alphetically sorted, nevermind.

Re: [PATCH v2 2/7] docs/devel: create "Developing QEMU" subsection

[John Snow]

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

On Fri, Aug 6, 2021 at 12:42 PM Philippe Mathieu-Daudé <f4bug@amsat.org>
wrote:

> On 8/6/21 6:40 PM, Philippe Mathieu-Daudé wrote:
> > On 8/6/21 5:51 PM, John Snow wrote:
> >> Signed-off-by: John Snow <jsnow@redhat.com>
> >> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
> >> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> >> ---
> >>  docs/devel/index.rst               |  6 +-----
> >>  docs/devel/section-development.rst | 12 ++++++++++++
> >>  2 files changed, 13 insertions(+), 5 deletions(-)
> >>  create mode 100644 docs/devel/section-development.rst
> >>
> >> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> >> index 008d489d751..57016edd841 100644
> >> --- a/docs/devel/index.rst
> >> +++ b/docs/devel/index.rst
> >> @@ -10,9 +10,7 @@ modifying QEMU's source code.
> >>     :includehidden:
> >>
> >>     section-community-governance
> >> -   build-system
> >> -   style
> >> -   kconfig
> >> +   section-development
> >>     testing
> >>     fuzzing
> >>     control-flow-integrity
> >> @@ -20,11 +18,9 @@ modifying QEMU's source code.
> >>     memory
> >>     migration
> >>     atomics
> >> -   stable-process
> >>     ci
> >>     qtest
> >>     decodetree
> >> -   secure-coding-practices
> >>     tcg
> >>     tcg-icount
> >>     tracing
> >> diff --git a/docs/devel/section-development.rst
> b/docs/devel/section-development.rst
> >> new file mode 100644
> >> index 00000000000..bba4fea30cb
> >> --- /dev/null
> >> +++ b/docs/devel/section-development.rst
> >> @@ -0,0 +1,12 @@
> >> +Developing QEMU
> >> +===============
> >> +
> >> +.. toctree::
> >> +   :maxdepth: 2
> >> +   :includehidden:
> >> +
> >
> > Could we order from generic to specific?
>
> Oh this is alphetically sorted, nevermind.
>
>
If you want to give them a better "armchair order", I personally welcome
it. A good intro paragraph or two directly in the section-*.rst that
introduces the contents to follow, alongside a brief copy-editing of the
layout and organization of the docs in the section would be very helpful.
It was just more than I wanted to tackle with a quick series.

[-- Attachment #2: Type: text/html, Size: 3181 bytes --]