[PATCH 1/2] doc: cgroup: use graphviz code instead of ASCII art

[PATCH 1/2] doc: cgroup: use graphviz code instead of ASCII art

[Otto Sabart]

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

The graphviz looks better. This patch also fixes multiple build warnings:
"WARNING: Block quote ends without a blank line; unexpected unindent."

Signed-off-by: Otto Sabart <ottosabart@seberm.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 83 ++++++++++++++++++++-----
 1 file changed, 66 insertions(+), 17 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 7bf3f129c68b..80c88a0869e4 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -344,10 +344,21 @@ example, to start a clean-up operation after all processes of a given
 sub-hierarchy have exited.  The populated state updates and
 notifications are recursive.  Consider the following sub-hierarchy
 where the numbers in the parentheses represent the numbers of processes
-in each cgroup::
+in each cgroup:
 
-  A(4) - B(0) - C(1)
-              \ D(0)
+.. kernel-render:: DOT
+  :alt: hierarchy
+
+  digraph subhierarchy {
+    edge [
+      arrowhead="none"
+    ];
+    rankdir=LR;
+
+    "A(4)" -> "B(0)";
+    "B(0)" -> "C(1)";
+    "B(0)" -> "D(0)";
+  }
 
 A, B and C's "populated" fields would be 1 while D's 0.  After the one
 process in C exits, B and C's "populated" fields would flip to "0" and
@@ -380,10 +391,21 @@ are specified, the last one is effective.
 Enabling a controller in a cgroup indicates that the distribution of
 the target resource across its immediate children will be controlled.
 Consider the following sub-hierarchy.  The enabled controllers are
-listed in parentheses::
+listed in parentheses:
+
+.. kernel-render:: DOT
+  :alt: hierarchy
 
-  A(cpu,memory) - B(memory) - C()
-                            \ D()
+  digraph subhierarchy {
+    edge [
+      arrowhead="none"
+    ];
+    rankdir=LR;
+
+    "A(cpu,memory)" -> "B(memory)";
+    "B(memory)" -> "C()";
+    "B(memory)" -> "D()";
+  }
 
 As A has "cpu" and "memory" enabled, A will control the distribution
 of CPU cycles and memory to its children, in this case, B.  As B has
@@ -497,12 +519,30 @@ in from or push out to outside the sub-hierarchy.
 
 For an example, let's assume cgroups C0 and C1 have been delegated to
 user U0 who created C00, C01 under C0 and C10 under C1 as follows and
-all processes under C0 and C1 belong to U0::
+all processes under C0 and C1 belong to U0:
+
+.. kernel-render:: DOT
+  :alt: cgroup hierarchy
 
-  ~~~~~~~~~~~~~ - C0 - C00
-  ~ cgroup    ~      \ C01
-  ~ hierarchy ~
-  ~~~~~~~~~~~~~ - C1 - C10
+  digraph hierarchyc0 {
+    edge [
+      arrowhead="none"
+    ];
+
+    "C0" -> "C00";
+    "C0" -> "C01";
+  }
+
+.. kernel-render:: DOT
+  :alt: cgroup hierarchy
+
+  digraph hierarchyc1 {
+    edge [
+      arrowhead="none"
+    ];
+
+    "C1" -> "C10";
+  }
 
 Let's also say U0 wants to write the PID of a process which is
 currently in C10 into "C00/cgroup.procs".  U0 has write access to the
@@ -1505,12 +1545,21 @@ The limits are only applied at the peer level in the hierarchy.  This means that
 in the diagram below, only groups A, B, and C will influence each other, and
 groups D and F will influence each other.  Group G will influence nobody.
 
-			[root]
-		/	   |		\
-		A	   B		C
-	       /  \        |
-	      D    F	   G
-
+.. kernel-render:: DOT
+  :alt: Peer hierarchy
+
+  digraph hierarchy {
+    edge [
+      arrowhead="none"
+    ];
+
+    "[root]" -> "A";
+    "[root]" -> "B";
+    "[root]" -> "C";
+    "A" -> "D";
+    "A" -> "F";
+    "B" -> "G";
+  }
 
 So the ideal way to configure this is to set io.latency in groups A, B, and C.
 Generally you do not want to set a value lower than the latency your device
-- 
2.17.2

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

Re: [PATCH 1/2] doc: cgroup: use graphviz code instead of ASCII art

[Jonathan Corbet]

On Sun, 30 Dec 2018 17:49:45 +0100
Otto Sabart <ottosabart@seberm.com> wrote:

> The graphviz looks better. This patch also fixes multiple build warnings:
> "WARNING: Block quote ends without a blank line; unexpected unindent."
> 
> Signed-off-by: Otto Sabart <ottosabart@seberm.com>

The graphviz looks better *in some settings*, such as the formatted
version of the docs.  Please remember, though, that we need to preserve
the readability of the plain-text documents as well, and my own feeling
is that this patch is a step backward in that regard.  I'll defer to
Tejun on this if he feels otherwise, but my sense is that this is not
something we want to do.

OTOH fixing the warnings would be a good thing; I think it just needs a
bit more use of literal blocks.  I would gladly accept a patch that did
just that.

Thanks,

jon

Re: [PATCH 1/2] doc: cgroup: use graphviz code instead of ASCII art

[Otto Sabart]

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


On 30. Dec (Sunday) v 10:40:29 -0700 2018, Jonathan Corbet wrote:
> On Sun, 30 Dec 2018 17:49:45 +0100
> Otto Sabart <ottosabart@seberm.com> wrote:
> 
> > The graphviz looks better. This patch also fixes multiple build warnings:
> > "WARNING: Block quote ends without a blank line; unexpected unindent."
> > 
> > Signed-off-by: Otto Sabart <ottosabart@seberm.com>
> 
> The graphviz looks better *in some settings*, such as the formatted
> version of the docs.  Please remember, though, that we need to preserve
> the readability of the plain-text documents as well, and my own feeling
> is that this patch is a step backward in that regard.  I'll defer to
> Tejun on this if he feels otherwise, but my sense is that this is not
> something we want to do.
> 
> OTOH fixing the warnings would be a good thing; I think it just needs a
> bit more use of literal blocks.  I would gladly accept a patch that did
> just that.

Ok, no problem. I will send another patch which fixes only these
warnings.

Thanks,

Ota

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

Re: [PATCH 1/2] doc: cgroup: use graphviz code instead of ASCII art

[Tejun Heo]

On Sun, Dec 30, 2018 at 10:40:29AM -0700, Jonathan Corbet wrote:
> On Sun, 30 Dec 2018 17:49:45 +0100
> Otto Sabart <ottosabart@seberm.com> wrote:
> 
> > The graphviz looks better. This patch also fixes multiple build warnings:
> > "WARNING: Block quote ends without a blank line; unexpected unindent."
> > 
> > Signed-off-by: Otto Sabart <ottosabart@seberm.com>
> 
> The graphviz looks better *in some settings*, such as the formatted
> version of the docs.  Please remember, though, that we need to preserve
> the readability of the plain-text documents as well, and my own feeling
> is that this patch is a step backward in that regard.  I'll defer to
> Tejun on this if he feels otherwise, but my sense is that this is not
> something we want to do.

Yeah, I'd much prefer to prioritize source file readability.  My
anecdotal experience is that most folks read the text file directly.

Thanks.

-- 
tejun