[RFC PATCH] docs/devel: try and impose some organisation

[RFC PATCH] docs/devel: try and impose some organisation

[Alex Bennée]

We have a growing set of developer docs but the index is currently in
order of when stuff was added. Try and make things a bit easier to
find my adding sub indexes and organising into themes.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/devel/index-api.rst       | 15 +++++++++++
 docs/devel/index-build.rst     | 20 +++++++++++++++
 docs/devel/index-internals.rst | 22 ++++++++++++++++
 docs/devel/index-process.rst   | 18 +++++++++++++
 docs/devel/index-tcg.rst       | 17 +++++++++++++
 docs/devel/index.rst           | 46 ++++++----------------------------
 6 files changed, 99 insertions(+), 39 deletions(-)
 create mode 100644 docs/devel/index-api.rst
 create mode 100644 docs/devel/index-build.rst
 create mode 100644 docs/devel/index-internals.rst
 create mode 100644 docs/devel/index-process.rst
 create mode 100644 docs/devel/index-tcg.rst

diff --git a/docs/devel/index-api.rst b/docs/devel/index-api.rst
new file mode 100644
index 0000000000..b749240272
--- /dev/null
+++ b/docs/devel/index-api.rst
@@ -0,0 +1,15 @@
+Internal QEMU APIs
+------------------
+
+Details about how QEMU's various internal APIs. Most of these are
+generated from in-code annotations to function prototypes.
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   bitops
+   loads-stores
+   memory
+   modules
+   ui
diff --git a/docs/devel/index-build.rst b/docs/devel/index-build.rst
new file mode 100644
index 0000000000..982ee801bd
--- /dev/null
+++ b/docs/devel/index-build.rst
@@ -0,0 +1,20 @@
+QEMU Build and Test System
+--------------------------
+
+Details about how QEMU's build system works and how it is integrated
+into our testing infrastructure. You will need to understand some of
+the basics if you are adding new files and targets to the build.
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   build-system
+   kconfig
+   testing
+   qtest
+   ci
+   qapi-code-gen
+   fuzzing
+   control-flow-integrity
+      
diff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst
new file mode 100644
index 0000000000..78270e89b3
--- /dev/null
+++ b/docs/devel/index-internals.rst
@@ -0,0 +1,22 @@
+Internal Subsystem Information
+------------------------------
+
+Details about QEMU's various subsystems including how to add features to them.
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   qom
+   atomics
+   block-coroutine-wrapper
+   clocks
+   ebpf_rss
+   migration
+   multi-process
+   reset
+   s390-dasd-ipl
+   tracing
+   vfio-migration
+   writing-monitor-commands
+      
diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst
new file mode 100644
index 0000000000..0290762c08
--- /dev/null
+++ b/docs/devel/index-process.rst
@@ -0,0 +1,18 @@
+QEMU Community Processes
+------------------------
+
+Notes about how to interact with the community and how and where to submit patches.
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   code-of-conduct
+   conflict-resolution
+   style
+   submitting-a-patch
+   trivial-patches
+   stable-process
+   submitting-a-pull-request
+   secure-coding-practices
+      
diff --git a/docs/devel/index-tcg.rst b/docs/devel/index-tcg.rst
new file mode 100644
index 0000000000..daa63e9a9a
--- /dev/null
+++ b/docs/devel/index-tcg.rst
@@ -0,0 +1,17 @@
+TCG Emulation
+-------------
+
+Details about QEMU's Tiny Code Generator and the infrastructure
+associated with emulation. You do not need to worry about this if you
+are only implementing things for HW accelerated hypervisors.
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   tcg
+   decodetree
+   multi-thread-tcg
+   tcg-icount
+   tcg-plugins
+      
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index afd937535e..a68207052d 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -7,44 +7,12 @@ You only need to read it if you are interested in reading or
 modifying QEMU's source code.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :includehidden:
 
-   code-of-conduct
-   conflict-resolution
-   build-system
-   style
-   kconfig
-   testing
-   fuzzing
-   control-flow-integrity
-   loads-stores
-   memory
-   migration
-   atomics
-   stable-process
-   ci
-   qtest
-   decodetree
-   secure-coding-practices
-   tcg
-   tcg-icount
-   tracing
-   multi-thread-tcg
-   tcg-plugins
-   bitops
-   ui
-   reset
-   s390-dasd-ipl
-   clocks
-   qom
-   modules
-   block-coroutine-wrapper
-   multi-process
-   ebpf_rss
-   vfio-migration
-   qapi-code-gen
-   writing-monitor-commands
-   trivial-patches
-   submitting-a-patch
-   submitting-a-pull-request
+
+   index-process
+   index-build
+   index-api
+   index-internals
+   index-tcg
-- 
2.30.2

Re: [RFC PATCH] docs/devel: try and impose some organisation

[Kashyap Chamarthy]

On Wed, Mar 09, 2022 at 01:53:55PM +0000, Alex Bennée wrote:
> We have a growing set of developer docs but the index is currently in
> order of when stuff was added. Try and make things a bit easier to
> find my adding sub indexes and organising into themes.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/devel/index-api.rst       | 15 +++++++++++
>  docs/devel/index-build.rst     | 20 +++++++++++++++
>  docs/devel/index-internals.rst | 22 ++++++++++++++++
>  docs/devel/index-process.rst   | 18 +++++++++++++
>  docs/devel/index-tcg.rst       | 17 +++++++++++++
>  docs/devel/index.rst           | 46 ++++++----------------------------
>  6 files changed, 99 insertions(+), 39 deletions(-)
>  create mode 100644 docs/devel/index-api.rst
>  create mode 100644 docs/devel/index-build.rst
>  create mode 100644 docs/devel/index-internals.rst
>  create mode 100644 docs/devel/index-process.rst
>  create mode 100644 docs/devel/index-tcg.rst

Yeah, the sub-indexes idea looks good to me.  It's good to start this
before it gets out of hand :-)

As discussed on IRC, there seems to be some whitespace damage:

    $> git describe
    v6.2.0-2381-g034e818c93
    
    $>  ~/Mail/patch-temp/cur/1647009097.180136_1.paraplu\:2\,S
    Applying: docs/devel: try and impose some organisation
    .git/rebase-apply/patch:61: trailing whitespace.
          
    .git/rebase-apply/patch:89: trailing whitespace.
          
    .git/rebase-apply/patch:113: trailing whitespace.
          
    .git/rebase-apply/patch:136: trailing whitespace.
          
    .git/rebase-apply/patch:61: new blank line at EOF.
    +
    warning: squelched 3 whitespace errors
    warning: 8 lines add whitespace errors.

FWIW:

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>    

[...]

-- 
/kashyap