Merge pull request #14499 from qlyoung/fix-doc-whitespace-toctree

fix various developer doc issues

doc/developer/building-frr-for-ubuntu2204.rst

@@ -58,6 +58,7 @@ If config rollbacks are enabled using ``--enable-config-rollbacks``
 the sqlite3 developer package also should be installed.
 
 .. code-block:: console
+
    sudo apt install libsqlite3-dev
 
 

doc/developer/checkpatch.rst

@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0-only
 
+.. _checkpatch:
+
 ==========
 Checkpatch
 ==========

doc/developer/cli.rst

@@ -639,13 +639,14 @@ in order into ``*argv[]``. Before this happens the ``->arg`` field is set to
 point at the snippet of user input that matched it.
 
 For most nontrivial commands the handler function will need to determine which
-of the possible matching inputs was entered. Previously this was done by looking
+of the possible matching inputs was entered. Previously this was done by
-at the first few characters of input. This is now considered an anti-pattern and
+looking at the first few characters of input. This is now considered an
-should be avoided. Instead, the ``->type`` or ``->text`` fields for this logic.
+anti-pattern and should be avoided. Instead, use the ``->type`` or ``->text``
-The ``->type`` field can be used when the possible inputs differ in type. When
+fields for this logic. The ``->type`` field can be used when the possible
-the possible types are the same, use the ``->text`` field. This field has the
+inputs differ in type. When the possible types are the same, use the ``->text``
-full text of the corresponding token in the definition string and using it makes
+field. This field has the full text of the corresponding token in the
-for much more readable code. An example is helpful.
+definition string and using it makes for much more readable code. An example is
+helpful.
 
 Command definition:
 
@@ -654,9 +655,10 @@ Command definition:
    command <(1-10)|foo|BAR>
 
 In this example, the user may enter any one of:
-- an integer between 1 and 10
+
-- "foo"
+* an integer between 1 and 10
-- anything at all
+* "foo"
+* anything at all
 
 If the user enters "command f", then:
 
@@ -793,12 +795,12 @@ Adding a CLI Node
 
 To add a new CLI node, you should:
 
-- define a new numerical node constant
+#. define a new numerical node constant
-- define a node structure in the relevant daemon
+#. define a node structure in the relevant daemon
-- call ``install_node()`` in the relevant daemon
+#. call ``install_node()`` in the relevant daemon
-- define and install the new node in vtysh
+#. define and install the new node in vtysh
-- define corresponding node entry commands in daemon and vtysh
+#. define corresponding node entry commands in daemon and vtysh
-- add a new entry to the ``ctx_keywords`` dictionary in ``tools/frr-reload.py``
+#. add a new entry to the ``ctx_keywords`` dictionary in ``tools/frr-reload.py``
 
 Defining the numerical node constant
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/developer/cspf.rst

@@ -24,59 +24,59 @@ to the cost of the cuurent path from the source up to the current node.
 
 The algorithm is as followed:
 
-```
+.. code-block:: c
-   cost = MAX_COST;
-	Priority_Queue.empty();
-	Visited_Node.empty();
-	Processed_Path.empty();
-   src = new_path(source_address);
-	src.cost = 0;
-   dst = new_destinatio(destination_address);
-   dst.cost = MAX_COST;
-	Processed_Path.add(src);
-	Processed_Path.add(dst);
-	while (Priority_Queue.count != 0) {
-		current_path = Priority_Queue.pop();
-		current_node = next_path.destination;
-      Visited_Node.add(current_node);
-		for (current_node.edges: edge) {
-			if (prune_edge(current_path, edge)
-				continue;
-			if (relax(current_path) && cost > current_path.cost) {
-				optim_path = current_path;
-				cost = current_path.cost;
-			}
-		}
-	}
 
-	prune_edge(path, edge) {
+    cost = MAX_COST;
-		// check that path + edge meet constraints  e.g.
+    Priority_Queue.empty();
-		if (current_path.cost + edge.cost > constrained_cost)
+    Visited_Node.empty();
-			return false;
+    Processed_Path.empty();
-		else
+    src = new_path(source_address);
-			return true;
+    src.cost = 0;
-	}
+    dst = new_destinatio(destination_address);
+    dst.cost = MAX_COST;
+    Processed_Path.add(src);
+    Processed_Path.add(dst);
+    while (Priority_Queue.count != 0) {
+        current_path = Priority_Queue.pop();
+        current_node = next_path.destination;
+        Visited_Node.add(current_node);
+        for (current_node.edges: edge) {
+            if (prune_edge(current_path, edge)
+                continue;
+            if (relax(current_path) && cost > current_path.cost) {
+                optim_path = current_path;
+                cost = current_path.cost;
+            }
+        }
+    }
 
-	relax_edge(current_path, edge) {
+    prune_edge(path, edge) {
-		next_node = edge.destination;
+        // check that path + edge meet constraints  e.g.
-		if (Visited_Node.get(next_node))
+        if (current_path.cost + edge.cost > constrained_cost)
-			return false;
+            return false;
-		next_path = Processed_Path.get(edge.destination);
+        else
-		if (!next_path) {
+            return true;
-			next_path = new path(edge.destination);
+    }
-			Processed_Path.add(next_path);
+
-		}
+    relax_edge(current_path, edge) {
-		total_cost = current_path.cost + edge.cost;
+        next_node = edge.destination;
-		if (total_cost < next_path.cost) {
+        if (Visited_Node.get(next_node))
-			next_path = current_path;
+            return false;
-			next_path.add_edge(edge);
+        next_path = Processed_Path.get(edge.destination);
-			next_path.cost = total_cost;
+        if (!next_path) {
-			Priority_Queue.add(next_path);
+            next_path = new path(edge.destination);
-		}
+            Processed_Path.add(next_path);
-		return (next_path.destination == destination);
+        }
-	}
+        total_cost = current_path.cost + edge.cost;
+        if (total_cost < next_path.cost) {
+            next_path = current_path;
+            next_path.add_edge(edge);
+            next_path.cost = total_cost;
+            Priority_Queue.add(next_path);
+        }
+        return (next_path.destination == destination);
+    }
 
-```
 
 Definition
 ----------
@@ -163,34 +163,34 @@ To perform a Path Computation with given constraints, proceed as follow:
 
 .. code-block:: c
 
-	struct cspf *algo;
+    struct cspf *algo;
-	struct ls_ted *ted;
+    struct ls_ted *ted;
-	struct in_addr src;
+    struct in_addr src;
-	struct in_addr dst;
+    struct in_addr dst;
-	struct constraints csts;
+    struct constraints csts;
-	struct c_path *path;
+    struct c_path *path;
 
-	// Create a new CSPF structure
+    // Create a new CSPF structure
-	algo = cspf_new();
+    algo = cspf_new();
 
-	// Initialize constraints
+    // Initialize constraints
-	csts.cost = 100;
+    csts.cost = 100;
-	csts.ctype = CSPF_TE_METRIC;
+    csts.ctype = CSPF_TE_METRIC;
-	csts.family = AF_INET;
+    csts.family = AF_INET;
-	csts.type = SR_TE;
+    csts.type = SR_TE;
-	csts.bw = 1000000;
+    csts.bw = 1000000;
-	csts.cos = 3;
+    csts.cos = 3;
 
-	// Then, initialise th CSPF with source, destination and constraints
+    // Then, initialise th CSPF with source, destination and constraints
-	cspf_init_v4(algo, ted, src, dst, &csts);
+    cspf_init_v4(algo, ted, src, dst, &csts);
 
-	// Finally, got the Computed Path;
+    // Finally, got the Computed Path;
-	path = compute_p2p_path(ted, algo);
+    path = compute_p2p_path(ted, algo);
 
-	if (path.status == SUCCESS)
+    if (path.status == SUCCESS)
-		zlog_info("Got a valid constraints path");
+        zlog_info("Got a valid constraints path");
-	else
+    else
-		zlog_info("Unable to compute constraints path. Got %d status", path->status);
+        zlog_info("Unable to compute constraints path. Got %d status", path->status);
 
 
 If you would compute another path, you must call `cspf_init()` prior to

doc/developer/index.rst

@@ -5,6 +5,7 @@ FRRouting Developer's Guide
    :maxdepth: 2
 
    workflow
+   checkpatch
    building
    packaging
    process-architecture

doc/developer/ospf.rst

@@ -9,4 +9,5 @@ OSPFD
 
    ospf-api
    ospf-sr
+   cspf
 

doc/developer/topotests.rst

@@ -472,8 +472,8 @@ For each capture a window is opened displaying a live summary of the captured
 packets. Additionally, the entire packet stream is captured in a pcap file in
 the tests log directory e.g.,::
 
-When using a unified log file `frr.log` one substitutes `frr` for the daemon
+When using a unified log file ``frr.log`` one substitutes ``frr`` for the
-name in the ``--logd`` CLI option, e.g.,
+daemon name in the ``--logd`` CLI option, e.g.,
 
 .. code:: shell
 
@@ -617,6 +617,8 @@ allocations upon exit. To enable also reporting of memory leaks to a specific
 location, define an environment variable ``TOPOTESTS_CHECK_MEMLEAK`` with the
 file prefix, i.e.:
 
+::
+
    export TOPOTESTS_CHECK_MEMLEAK="/home/mydir/memleak_"
 
 For tests that support the TOPOTESTS_CHECK_MEMLEAK environment variable, this

doc/developer/workflow.rst

@@ -817,6 +817,7 @@ The project provides multiple tools to allow you to correctly style your code
 as painlessly as possible, primarily built around ``clang-format``.
 
 clang-format
+
    In the project root there is a :file:`.clang-format` configuration file
    which can be used with the ``clang-format`` source formatter tool from the
    LLVM project. Most of the time, this is the easiest and smartest tool to
@@ -875,6 +876,8 @@ clang-format
 checkpatch.sh
 checkpatch.pl
 
+   .. seealso:: :ref:`checkpatch`
+
    In the Linux kernel source tree there is a Perl script used to check
    incoming patches for style errors. FRR uses a shell script front end and an
    adapted version of the perl script for the same purpose. These scripts can