From aaa9512d5089743bbea54f0e253a32d3c17a8d50 Mon Sep 17 00:00:00 2001
From: Martine Lenders <m.lenders@fu-berlin.de>
Date: Wed, 10 Feb 2021 15:47:06 +0100
Subject: [PATCH] doc/porting-boards.md: improve with porting graph and
 reference section

---
 doc/doxygen/dot/porting-boards.dot | 96 ++++++++++++++++++++++++++++++
 doc/doxygen/riot.doxyfile          |  3 +-
 doc/doxygen/src/porting-boards.md  | 13 ++++
 doc/doxygen/src/porting-cpus.md    |  4 --
 4 files changed, 110 insertions(+), 6 deletions(-)
 create mode 100644 doc/doxygen/dot/porting-boards.dot
 delete mode 100644 doc/doxygen/src/porting-cpus.md

diff --git a/doc/doxygen/dot/porting-boards.dot b/doc/doxygen/dot/porting-boards.dot
new file mode 100644
index 0000000000..3b70c1c30c
--- /dev/null
+++ b/doc/doxygen/dot/porting-boards.dot
@@ -0,0 +1,96 @@
+strict digraph {
+  graph [
+    splines=true,
+  ]
+  node [
+    style="filled",
+    fontname="sans-serif",
+    color="#3fa687",
+    fillcolor="#275a4b",
+    fontcolor="white",
+    shape="box",
+    penwidth=2,
+    width=4.1,
+  ];
+  edge [
+    color="#3fa687",
+    fontcolor="#275a4b",
+    fontname="sans-serif",
+    penwidth=2,
+    labelfloat=true,
+  ];
+
+  Start [shape="Mrecord", width=0.75];
+  End [
+    label="Blink the LEDs",
+    tooltip="Blink the LEDs",
+    shape="Mrecord",
+    URL="https://github.com/RIOT-OS/RIOT/tree/master/tests/leds",
+  ];
+
+  IfCPU [
+    label=<CPU/MCU<BR/>already ported?>,
+    tooltip="CPU/MCU already ported?",
+    shape="diamond",
+  ];
+  IfBoard [
+    label=<Board definitions<BR/>already provided?>,
+    tooltip="Board definitions already provided?",
+    shape="diamond",
+  ];
+  IfDrivers [
+    label=<All on-board<BR/>devices supported?>,
+    tooltip="All on-board devices supported?",
+    shape="diamond",
+  ];
+  IfNetdev [
+    label=<Network device<BR/>supported by<BR/>network stack?>,
+    tooltip="Network device supported by network stack?",
+    shape="diamond"
+  ];
+
+  PortCPU [
+    label=<Port <B>CPU</B><BR/>(TBD: provide guide)>,
+    tooltip="Port CPU",
+  ];
+  PortBoard [
+    label=<Provide<BR/><B>board definitions</B>>,
+    tooltip="Provide board definitions",
+    URL="@ref porting-boards",
+  ];
+  PortDrivers [
+    label=<Provide<BR/><B>device drivers</B>>,
+    tooltip="Provide device drivers",
+    URL="@ref driver-guide",
+  ];
+  PortNetdev [
+    label=<Provide <B>network device support</B><BR/>for network stack>,
+    tooltip="Provide network device support for network stack",
+    URL="@ref drivers_netdev",
+  ];
+
+  Start -> IfCPU;
+  IfCPU -> IfBoard [label="Yes"];
+  IfBoard -> IfDrivers [label="Yes"];
+  IfDrivers -> IfNetdev [label="Yes"];
+  IfNetdev -> End [label="Yes"];
+
+  IfCPU -> PortCPU [label="No"];
+  IfBoard -> PortBoard [label="No"];
+  IfDrivers -> PortDrivers [label="No"];
+  IfNetdev -> PortNetdev [label="No"];
+
+  PortCPU -> IfBoard;
+  PortBoard -> IfDrivers;
+  PortDrivers -> IfNetdev;
+  PortNetdev -> End;
+
+  /* ensure No branch is on same row as If */
+  {rank=same; IfCPU PortCPU}
+  {rank=same; IfBoard PortBoard}
+  {rank=same; IfDrivers PortDrivers}
+  {rank=same; IfNetdev PortNetdev}
+  /* ensure PortNodes are on top of each other */
+  edge [style="invis"];
+  PortCPU -> PortBoard -> PortDrivers -> PortNetdev;
+}
diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile
index 01fe5ea21a..1a5e3d47e3 100644
--- a/doc/doxygen/riot.doxyfile
+++ b/doc/doxygen/riot.doxyfile
@@ -765,7 +765,6 @@ INPUT                  = ../../doc.txt \
                          src/creating-modules.md \
                          src/creating-an-application.md \
                          src/porting-boards.md \
-                         src/porting-cpus.md \
                          src/driver-guide.md \
                          src/getting-started.md \
                          ../../tests/README.md \
@@ -2331,7 +2330,7 @@ DOT_PATH               =
 # command).
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOTFILE_DIRS           =
+DOTFILE_DIRS           = dot/
 
 # The MSCFILE_DIRS tag can be used to specify one or more directories that
 # contain msc files that are included in the documentation (see the \mscfile
diff --git a/doc/doxygen/src/porting-boards.md b/doc/doxygen/src/porting-boards.md
index 7a0809b87c..c7ef8be0ad 100644
--- a/doc/doxygen/src/porting-boards.md
+++ b/doc/doxygen/src/porting-boards.md
@@ -15,6 +15,9 @@ to `RIOT`, the different files as well as their functionality.
 @note We assume here that your `CPU` and `CPU_MODEL` is already supported
 in `RIOT` so no peripheral or cpu implementation is needed.
 
+# Porting flowchart                                         {#porting-flowchart}
+@dotfile porting-boards.dot
+
 # General structure                                         {#general-structure}
 
 Like @ref creating-an-application "applications" or @ref creating-modules
@@ -334,3 +337,13 @@ Some scripts and tools available to ease `BOARD` porting and testing:
 
   - Run `dist/tools/compile_and_test_for_board/compile_and_test_for_board.py . <board> --with-test-only`
     to run all automated tests on the new board.
+
+# Further reference                                         {#further-reference}
+
+- [In her blog][martines-blog], Martine Lenders documented her approach of
+  porting the @ref boards_feather-nrf52840 in February 2020.
+- [Over at HackMD][hackmd-slstk3400a], Akshai M documented his approach of
+  porting the @ref boards_slstk3400a in July 2020.
+
+[martines-blog]: https://blog.martine-lenders.eu/riot-board-en.html
+[hackmd-slstk3400a]: https://hackmd.io/njFHwQ33SNS3sQKAkLkNtQ
diff --git a/doc/doxygen/src/porting-cpus.md b/doc/doxygen/src/porting-cpus.md
deleted file mode 100644
index 325c1652c1..0000000000
--- a/doc/doxygen/src/porting-cpus.md
+++ /dev/null
@@ -1,4 +0,0 @@
-Porting CPUs                                                     {#porting-cpus}
-============
-
-@todo Add dot graph with different options, describe options