doc/dev: add section on using the gen_state_diagram.py script

Commands sourced from Jianshen Liu's blog post on the Ceph peering state machine: https://jianshenliu.com/blog/development/ceph-peering-state-machine/

Also fixed the formatting of "PG info".

Signed-off-by: Laura Flores <lflores@redhat.com>

diff --git a/doc/dev/peering.rst b/doc/dev/peering.rst
index 7ee5debc9caf01f851baec3f267b73f44cb4cfa5..3960e14ca33a82509d490410fe5366927c7e7ad6 100644 (file)
--- a/doc/dev/peering.rst
+++ b/doc/dev/peering.rst
@@ -60,7 +60,8 @@ Concepts
    accepting write operations, and *recovery* can proceed
    in the background.
 
-*PG info* basic metadata about the PG's creation epoch, the version
+*PG info*
+   basic metadata about the PG's creation epoch, the version
    for the most recent write to the PG, *last epoch started*, *last
    epoch clean*, and the beginning of the *current interval*.  Any
    inter-OSD communication about PGs includes the *PG info*, such that
@@ -253,7 +254,17 @@ The high level process is for the current PG primary to:
      old object (all of whose copies disappeared before they could be
      replicated on members of the current *acting set*).
 
-State Model
------------
+Generate a State Model
+----------------------
+
+Use the `gen_state_diagram.py <https://github.com/ceph/ceph/blob/master/doc/scripts/gen_state_diagram.py>`_ script to generate a copy of the latest peering state model::
+
+        $ git clone https://github.com/ceph/ceph.git
+        $ cd ceph
+        $ cat src/osd/PeeringState.h src/osd/PeeringState.cc | doc/scripts/gen_state_diagram.py > doc/dev/peering_graph.generated.dot
+        $ sed -i 's/7,7/1080,1080/' doc/dev/peering_graph.generated.dot
+        $ dot -Tsvg doc/dev/peering_graph.generated.dot > doc/dev/peering_graph.generated.svg
+
+Sample state model:
 
 .. graphviz:: peering_graph.generated.dot

diff --git a/doc/scripts/README.md b/doc/scripts/README.md
new file mode 100644 (file)
index 0000000..e3d4c23
--- /dev/null
+++ b/doc/scripts/README.md
@@ -0,0 +1,11 @@
+Script Usage
+============
+
+Peering State Model: gen_state_diagram.py
+------------------------------------------
+    $ git clone https://github.com/ceph/ceph.git
+    $ cd ceph
+    $ cat src/osd/PeeringState.h src/osd/PeeringState.cc | doc/scripts/gen_state_diagram.py > doc/dev/peering_graph.generated.dot
+    $ sed -i 's/7,7/1080,1080/' doc/dev/peering_graph.generated.dot
+    $ dot -Tsvg doc/dev/peering_graph.generated.dot > doc/dev/peering_graph.generated.svg
+