Add cbi-tree example to the analysis tutorial

Signed-off-by: John Pennycook <[email protected]>

Author: Pennycook

docs/source/analysis.rst

@@ -104,6 +104,100 @@ platforms. Plugging these numbers into the equation for code divergence gives
     not to (more on that later).
 
 
+Running ``cbi-tree``
+####################
+
+Running ``codebasin`` provides an overview of divergence and coverage, which
+can be useful when we want to familiarize ourselves with a new code base,
+compare the impact of different code structures upon certain metrics, or track
+specialization metrics over time. However, it doesn't provide any *actionable*
+insight into how to improve a code base.
+
+To understand how much specialization exists in each source file, we can
+substitute ``codebasin`` for ``cbi-tree``::
+
+    $ cbi-tree analysis.toml
+
+This command performs the same analysis as ``codebasin``, but produces a tree
+annotated with information about which files contain specialization:
+
+.. code-block:: text
+   :emphasize-lines: 8,9,11,16
+
+    Legend:
+    A: cpu
+    B: gpu
+
+    Columns:
+    [Platforms | SLOC | Coverage (%) | Avg. Coverage (%)]
+
+    [AB | 33 |  93.94 |  72.73] o /home/username/code-base-investigator/docs/sample-code-base/src/
+    [AB | 13 | 100.00 |  92.31] ├── main.cpp
+    [A- |  7 |  85.71 |  42.86] ├─o cpu/
+    [A- |  7 |  85.71 |  42.86] │ └── foo.cpp
+    [AB |  6 | 100.00 | 100.00] ├─o third-party/
+    [AB |  1 | 100.00 | 100.00] │ ├── library.h
+    [AB |  5 | 100.00 | 100.00] │ └── library.cpp
+    [-B |  7 |  85.71 |  42.86] └─o gpu/
+    [-B |  7 |  85.71 |  42.86]   └── foo.cpp
+
+.. tip::
+
+    Running ``cbi-tree`` in a modern terminal environment producers colored
+    output to improve usability for large code bases.
+
+Each node in the tree represents a source file or directory in the code
+base and is annotated with four pieces of information:
+
+1. **Platforms**
+
+   The set of platforms that use the file or directory.
+
+2. **SLOC**
+
+   The number of source lines of code (SLOC) in the file or directory.
+
+3. **Coverage (%)**
+
+   The amount of code in the file or directory that is used by all platforms,
+   as a percentage of SLOC.
+
+4. **Avg. Coverage (%)**
+
+   The amount of code in the file or directory that is used by each platform,
+   on average, as a percentage of SLOC.
+
+The root of the tree represents the entire code base, and so the values in
+the annotations match the ``codebasin`` results: two platforms (``A`` and
+``B``) use the directory, there are 33 lines in total, 93.94% of those lines
+(i.e., 31 lines) are used by at least one platform, and each platform uses
+72.73% of those lines (i.e., 24 lines) on average. By walking the tree, we can
+break these numbers down across the individual files and directories in the
+code base.
+
+Starting with ``main.cpp``, we can see that it is used by both platforms
+(``A`` and ``B``), and that 100% of the 13 lines in the file are used by at
+least one platform. However, the average coverage is only 92.31%, reflecting
+that each platform uses only 12 of those lines.
+
+Turning our attention to ``cpu/foo.cpp`` and ``gpu/foo.cpp``, we can see
+that they are each specialized for one platform (``A`` and ``B``,
+respectively). The coverage for both files is only 85.71% (i.e., 6 of the 7
+lines), which tells us that both files contain some unused code (i.e., 1 line).
+The average coverage of 42.86% highlights the extent of the specialization.
+
+.. tip::
+
+   Looking at average coverage is the best way to identify highly specialized
+   regions of code. As the number of platforms targeted by a code base
+   increases, the average coverage for files used by only a small number of
+   platforms will approach zero.
+
+The remaining files all have a coverage of 100.00% and an average coverage
+of 100.00%. This is our ideal case: all of the code in the file is used by
+at least one platform, and all of the platforms use all of the code.
+
+
 Filtering Platforms
 ###################
 
@@ -125,3 +219,9 @@ platform as follows:
 .. code:: sh
 
     $ codebasin -p cpu analysis.toml
+
+or
+
+.. code:: sh
+
+    $ cbi-tree -p cpu analysis.toml