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

[PATCH 0/6] 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.

John Snow (6):
  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 "Miscellaneous Topics" subsection

 docs/devel/index.rst                        | 39 ++++-----------------
 docs/devel/section-community-governance.rst |  9 +++++
 docs/devel/section-development.rst          | 12 +++++++
 docs/devel/section-misc.rst                 | 15 ++++++++
 docs/devel/section-subsystems.rst           | 16 +++++++++
 docs/devel/section-tcg.rst                  | 11 ++++++
 docs/devel/section-testing-debugging.rst    | 12 +++++++
 7 files changed, 81 insertions(+), 33 deletions(-)
 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 1/6] 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>
---
 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 153979caf4b..f32883da8ed 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 2/6] docs/devel: create "Developing QEMU" subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 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 f32883da8ed..3cdfb786f1a 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 3/6] docs/devel: create "Testing & Debugging" subsection

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 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 3cdfb786f1a..c560cc78497 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 4/6] docs/devel: create TCG subsection

[John Snow]

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

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index c560cc78497..71ed48881ef 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -12,16 +12,13 @@ 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..ff046983742
--- /dev/null
+++ b/docs/devel/section-tcg.rst
@@ -0,0 +1,11 @@
+TCG - Tiny Code Generator
+=========================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   tcg
+   tcg-icount
+   multi-thread-tcg
+   tcg-plugins
-- 
2.31.1

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

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>

---

I tried to grab documents that appeared to document literal internal
interfaces of QEMU (that weren't better described by some other
subsection) and put them here in this section.

Name isn't perfect, feel free to suggest alternatives.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 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 71ed48881ef..da579a7b666 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -13,19 +13,11 @@ modifying QEMU's source code.
    section-development
    section-testing-debugging
    section-tcg
+   section-subsystems
    control-flow-integrity
-   loads-stores
-   memory
-   migration
-   atomics
    decodetree
-   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 6/6] 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>
---
 docs/devel/index.rst        |  9 +--------
 docs/devel/section-misc.rst | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 8 deletions(-)
 create mode 100644 docs/devel/section-misc.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index da579a7b666..ef14f3302e1 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -14,11 +14,4 @@ modifying QEMU's source code.
    section-testing-debugging
    section-tcg
    section-subsystems
-   control-flow-integrity
-   decodetree
-   s390-dasd-ipl
-   qom
-   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..804852ff61c
--- /dev/null
+++ b/docs/devel/section-misc.rst
@@ -0,0 +1,15 @@
+Miscellaneous Topics
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   control-flow-integrity
+   decodetree
+   s390-dasd-ipl
+   qom
+   block-coroutine-wrapper
+   multi-process
+   ebpf_rss
+   vfio-migration
-- 
2.31.1

Re: [PATCH 0/6] docs/devel: Organize devel manual into further subsections

[Peter Maydell]

On Wed, 4 Aug 2021 at 01:56, John Snow <jsnow@redhat.com> wrote:
>
> 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.
>
> John Snow (6):
>   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 "Miscellaneous Topics" subsection

I think 'decodetree' should also live in the TCG subsection;
otherwise, whole series
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 1/6] docs/devel: create "Community & Governance" subsection

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

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

-- 
Alex Bennée

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

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Re: [PATCH 3/6] docs/devel: create "Testing & Debugging" subsection

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Re: [PATCH 4/6] docs/devel: create TCG subsection

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>

modulo Peter's comments re decodetree:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Re: [PATCH 5/6] docs/devel: create "Subsystem APIs" subsection

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Re: [PATCH 6/6] docs/devel: create "Miscellaneous Topics" subsection

[Alex Bennée]

John Snow <jsnow@redhat.com> writes:

> 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>
> ---
>  docs/devel/index.rst        |  9 +--------
>  docs/devel/section-misc.rst | 15 +++++++++++++++
>  2 files changed, 16 insertions(+), 8 deletions(-)
>  create mode 100644 docs/devel/section-misc.rst
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index da579a7b666..ef14f3302e1 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -14,11 +14,4 @@ modifying QEMU's source code.
>     section-testing-debugging
>     section-tcg
>     section-subsystems
> -   control-flow-integrity
> -   decodetree

decodetree is TCG as per Peter's comment

> -   s390-dasd-ipl
> -   qom

I feel as though QOM should be in the Developing QEMU section as it's a
fairly core part of the programming experience. Maybe?

Anyway it's an improvement:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Re: [PATCH 4/6] docs/devel: create TCG subsection

[John Snow]

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

On Thu, Aug 5, 2021 at 8:09 AM Alex Bennée <alex.bennee@linaro.org> wrote:

>
> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> modulo Peter's comments re decodetree:
>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
>
> --
> Alex Bennée
>
>
OK, I'm making that change. Thanks!

--js

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

Re: [PATCH 6/6] docs/devel: create "Miscellaneous Topics" subsection

[John Snow]

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

On Thu, Aug 5, 2021 at 8:13 AM Alex Bennée <alex.bennee@linaro.org> wrote:

>
> John Snow <jsnow@redhat.com> writes:
>
> > 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>
> > ---
> >  docs/devel/index.rst        |  9 +--------
> >  docs/devel/section-misc.rst | 15 +++++++++++++++
> >  2 files changed, 16 insertions(+), 8 deletions(-)
> >  create mode 100644 docs/devel/section-misc.rst
> >
> > diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> > index da579a7b666..ef14f3302e1 100644
> > --- a/docs/devel/index.rst
> > +++ b/docs/devel/index.rst
> > @@ -14,11 +14,4 @@ modifying QEMU's source code.
> >     section-testing-debugging
> >     section-tcg
> >     section-subsystems
> > -   control-flow-integrity
> > -   decodetree
>
> decodetree is TCG as per Peter's comment
>
> > -   s390-dasd-ipl
> > -   qom
>
> I feel as though QOM should be in the Developing QEMU section as it's a
> fairly core part of the programming experience. Maybe?
>
>
I'm guilty of doing a lot of things in parallel, because I wasn't sure
which things would be accepted quickly and which might lead to a longer
process, but I intend to create an "API" section that covers QOM, qdev,
QMP, etc -- I just recently converted the qmp/qapi docs, so there's enough
for a nice subsection there.


> Anyway it's an improvement:
>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
>
>
Thanks. I'll have to re-spin anyway because of the QAPI doc work I did, so
there's time to talk about this one.

--js

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