From 8a1f7d299c75468af0f761ae9382b129be9d5774 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 7 Sep 2021 15:58:12 +0200 Subject: docs: standardize book titles to === with overline Documents within a Sphinx manual are separate files and therefore can use different conventions for headings. However, keeping some consistency is useful so that included files are easy to get right. This patch uses a standard heading format for book titles, so that it is obvious when a file sits at the top level toctree of a book or man page. The heading is irrelevant for man pages, but keep it consistent as well. Reviewed-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/index.rst | 1 + docs/system/qemu-block-drivers.rst | 1 + docs/system/qemu-cpu-models.rst | 1 + docs/system/qemu-manpage.rst | 5 +++-- docs/tools/qemu-img.rst | 1 + docs/tools/qemu-nbd.rst | 1 + docs/tools/qemu-pr-helper.rst | 1 + docs/tools/qemu-storage-daemon.rst | 1 + docs/tools/qemu-trace-stap.rst | 1 + 9 files changed, 11 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 5f7eaaa632..0b9ee9901d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +================================ Welcome to QEMU's documentation! ================================ diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst index bd99d4fa8e..eb276481d6 100644 --- a/docs/system/qemu-block-drivers.rst +++ b/docs/system/qemu-block-drivers.rst @@ -1,5 +1,6 @@ :orphan: +============================ QEMU block drivers reference ============================ diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst index 53d7538c47..8c51e2bf49 100644 --- a/docs/system/qemu-cpu-models.rst +++ b/docs/system/qemu-cpu-models.rst @@ -1,5 +1,6 @@ :orphan: +================================== QEMU / KVM CPU model configuration ================================== diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst index e9a25d0680..d6f44e265b 100644 --- a/docs/system/qemu-manpage.rst +++ b/docs/system/qemu-manpage.rst @@ -6,8 +6,9 @@ parts of the documentation that go in the manpage as well as the HTML manual. -Title -===== +======================= +QEMU User Documentation +======================= Synopsis -------- diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index b7d602a288..fe6c30d509 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -1,3 +1,4 @@ +======================= QEMU disk image utility ======================= diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst index ee862fa0bc..e39a9f4b1a 100644 --- a/docs/tools/qemu-nbd.rst +++ b/docs/tools/qemu-nbd.rst @@ -1,3 +1,4 @@ +===================================== QEMU Disk Network Block Device Server ===================================== diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst index ac036180ac..eaebe40da0 100644 --- a/docs/tools/qemu-pr-helper.rst +++ b/docs/tools/qemu-pr-helper.rst @@ -1,3 +1,4 @@ +================================== QEMU persistent reservation helper ================================== diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst index 3ec4bdd914..b8ef4486f1 100644 --- a/docs/tools/qemu-storage-daemon.rst +++ b/docs/tools/qemu-storage-daemon.rst @@ -1,3 +1,4 @@ +=================== QEMU Storage Daemon =================== diff --git a/docs/tools/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst index fb70445c75..d53073b52b 100644 --- a/docs/tools/qemu-trace-stap.rst +++ b/docs/tools/qemu-trace-stap.rst @@ -1,3 +1,4 @@ +========================= QEMU SystemTap trace tool ========================= -- cgit v1.2.3-55-g7522 From 06905f640242c927f07e8c4b45fd4061ffa235ef Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 7 Sep 2021 16:01:28 +0200 Subject: docs: standardize directory index to --- with overline Use a standard heading format for the index.rst file in a directory. Using overlines makes it clear that individual documents can use e.g. === for chapter titles and --- for section titles, as suggested in the Linux kernel guidelines[1]. They could do it anyway, because documents included in a toctree are parsed separately and therefore are not tied to the same conventions for headings. However, keeping some consistency is useful since sometimes files are included from multiple places. [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html Reviewed-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/about/index.rst | 3 ++- docs/devel/index.rst | 3 ++- docs/interop/index.rst | 3 ++- docs/specs/index.rst | 3 ++- docs/system/index.rst | 3 ++- docs/tools/index.rst | 3 ++- docs/user/index.rst | 3 ++- 7 files changed, 14 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/about/index.rst b/docs/about/index.rst index beb762aa0a..5bea653c07 100644 --- a/docs/about/index.rst +++ b/docs/about/index.rst @@ -1,5 +1,6 @@ +---------- About QEMU -========== +---------- QEMU is a generic and open source machine emulator and virtualizer. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 5522db7241..f95df10b3e 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -1,5 +1,6 @@ +--------------------- Developer Information -===================== +--------------------- This section of the manual documents various parts of the internals of QEMU. You only need to read it if you are interested in reading or diff --git a/docs/interop/index.rst b/docs/interop/index.rst index f9801a9c20..47b9ed82bb 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -1,5 +1,6 @@ +------------------------------------------------ System Emulation Management and Interoperability -================================================ +------------------------------------------------ This section of the manual contains documents and specifications that are useful for making QEMU interoperate with other software. diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 65e9663916..ecc43896bb 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -1,5 +1,6 @@ +---------------------------------------------- System Emulation Guest Hardware Specifications -============================================== +---------------------------------------------- This section of the manual contains specifications of guest hardware that is specific to QEMU. diff --git a/docs/system/index.rst b/docs/system/index.rst index 7b9276c05f..73bbedbc22 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -1,5 +1,6 @@ +---------------- System Emulation -================ +---------------- This section of the manual is the overall guide for users using QEMU for full system emulation (as opposed to user-mode emulation). diff --git a/docs/tools/index.rst b/docs/tools/index.rst index ef6041a490..1edd5a8054 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -1,5 +1,6 @@ +----- Tools -===== +----- This section of the manual documents QEMU's "tools": its command line utilities and other standalone programs. diff --git a/docs/user/index.rst b/docs/user/index.rst index 9faa4badd7..2c4e29f3db 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,5 +1,6 @@ +------------------- User Mode Emulation -=================== +------------------- This section of the manual is the overall guide for users using QEMU for user-mode emulation. In this mode, QEMU can launch -- cgit v1.2.3-55-g7522 From f0c1507a2b75d02d2b11aaf881cc5e722c250dc0 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 7 Sep 2021 17:33:27 +0200 Subject: docs/system: standardize man page sections to --- with overline Man pages in docs/system use file inclusion heavily. Use headings with overlines in the main files, so that the same included file work well from both manuals and man pages. This style of heading is a bit more heavy-weight, so it is not used by the other man pages in interop/ and tools/. If in the future they are changed to use include files, for example to avoid having sections named "synopsis" or "description", they can switch to --- with overline as well. Reviewed-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/system/qemu-block-drivers.rst | 3 +++ docs/system/qemu-cpu-models.rst | 9 ++++++--- docs/system/qemu-manpage.rst | 5 +++++ 3 files changed, 14 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst index eb276481d6..c2c0114cec 100644 --- a/docs/system/qemu-block-drivers.rst +++ b/docs/system/qemu-block-drivers.rst @@ -4,16 +4,19 @@ QEMU block drivers reference ============================ +-------- Synopsis -------- QEMU block driver reference manual +----------- Description ----------- .. include:: qemu-block-drivers.rst.inc +-------- See also -------- diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst index 8c51e2bf49..5cf6e46f8a 100644 --- a/docs/system/qemu-cpu-models.rst +++ b/docs/system/qemu-cpu-models.rst @@ -4,18 +4,21 @@ QEMU / KVM CPU model configuration ================================== +-------- Synopsis -'''''''' +-------- QEMU CPU Modelling Infrastructure manual +----------- Description -''''''''''' +----------- .. include:: cpu-models-x86.rst.inc .. include:: cpu-models-mips.rst.inc +-------- See also -'''''''' +-------- The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation. diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst index d6f44e265b..c47a412758 100644 --- a/docs/system/qemu-manpage.rst +++ b/docs/system/qemu-manpage.rst @@ -10,6 +10,7 @@ QEMU User Documentation ======================= +-------- Synopsis -------- @@ -17,11 +18,13 @@ Synopsis |qemu_system| [options] [disk_image] +----------- Description ----------- .. include:: target-i386-desc.rst.inc +------- Options ------- @@ -34,11 +37,13 @@ not need a disk image. .. include:: mux-chardev.rst.inc +----- Notes ----- .. include:: device-url-syntax.rst.inc +-------- See also -------- -- cgit v1.2.3-55-g7522 From c2c7f3351ad8d3230f190740e174365965f6f6b3 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 7 Sep 2021 16:08:59 +0200 Subject: docs/system: move x86 CPU configuration to a separate document Currently, cpu-models-x86.rst.inc is included in target-i386.rst directly. To make the toctree more homogeneous when adding more documentation, include it through a first-class .rst file. Together with the previous changes to the man page skeletons, this also frees "===" for the headings, so that cpu-models-x86.rst.inc need not assume anything about the headings used by target-i386.rst. Reviewed-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/system/cpu-models-x86.rst.inc | 4 ++-- docs/system/i386/cpu.rst | 1 + docs/system/target-i386.rst | 8 +++++++- 3 files changed, 10 insertions(+), 3 deletions(-) create mode 100644 docs/system/i386/cpu.rst (limited to 'docs') diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc index 9119f5dff5..6e8be7d79b 100644 --- a/docs/system/cpu-models-x86.rst.inc +++ b/docs/system/cpu-models-x86.rst.inc @@ -1,5 +1,5 @@ Recommendations for KVM CPU model configuration on x86 hosts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================================ The information that follows provides recommendations for configuring CPU models on x86 hosts. The goals are to maximise performance, while @@ -368,7 +368,7 @@ featureset, which prevents guests having optimal performance. Syntax for configuring CPU models -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================= The examples below illustrate the approach to configuring the various CPU models / features in QEMU and libvirt. diff --git a/docs/system/i386/cpu.rst b/docs/system/i386/cpu.rst new file mode 100644 index 0000000000..738719da9a --- /dev/null +++ b/docs/system/i386/cpu.rst @@ -0,0 +1 @@ +.. include:: ../cpu-models-x86.rst.inc diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index 22ba5ce2c0..c9720a8cd1 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -19,7 +19,13 @@ Board-specific documentation i386/microvm i386/pc -.. include:: cpu-models-x86.rst.inc +Architectural features +~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + i386/cpu .. _pcsys_005freq: -- cgit v1.2.3-55-g7522 From d97327342ea8b32ede19fadaf8290dc29fcfa048 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Thu, 9 Sep 2021 16:25:55 +0200 Subject: docs: link to archived Fedora code of conduct Fedora has switched to a different CoC. QEMU's own code of conduct is based on the previous version and cites it as a source. Replace the link with one to the Wayback Machine. Reviewed-by: Markus Armbruster Signed-off-by: Paolo Bonzini --- docs/devel/code-of-conduct.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/devel/code-of-conduct.rst b/docs/devel/code-of-conduct.rst index 277b5250d1..195444d1b4 100644 --- a/docs/devel/code-of-conduct.rst +++ b/docs/devel/code-of-conduct.rst @@ -55,6 +55,6 @@ Sources ------- This document is based on the `Fedora Code of Conduct -`__ and the -`Contributor Covenant version 1.3.0 +`__ +(as of April 2021) and the `Contributor Covenant version 1.3.0 `__. -- cgit v1.2.3-55-g7522