gh-36846: Resolve nice tree decomp bug in #36843, and allow `label_ni…

…ce_tree_decomposition` to return a digraph

    
This PR aims to resolve #36843, i.e., it now handles potential join
nodes and singleton tree decomp correctly.

This PR also allows `label_nice_tree_decomposition` to return a directed
graph, and treats the root node as a `forget` node, simplifying
algorithm implementation.

<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #36846
Reported by: Jing Guo
Reviewer(s): David Coudert, Dima Pasechnik, Jing Guo

src/sage/graphs/graph_decompositions/tree_decomposition.pyx

@@ -1083,37 +1083,31 @@ def label_nice_tree_decomposition(nice_TD, root, directed=False):
     EXAMPLES::
 
         sage: from sage.graphs.graph_decompositions.tree_decomposition import make_nice_tree_decomposition, label_nice_tree_decomposition
-        sage: bip_one_four = graphs.CompleteBipartiteGraph(1, 4)
-        sage: bip_one_four_TD = bip_one_four.treewidth(certificate=True)
-        sage: nice_TD = make_nice_tree_decomposition(bip_one_four, bip_one_four_TD)
+        sage: claw = graphs.CompleteBipartiteGraph(1, 3)
+        sage: claw_TD = claw.treewidth(certificate=True)
+        sage: nice_TD = make_nice_tree_decomposition(claw, claw_TD)
         sage: root = sorted(nice_TD.vertices())[0]
         sage: label_TD = label_nice_tree_decomposition(nice_TD, root, directed=True)
-        sage: print(label_TD.name())
-        Labelled Nice tree decomposition of Tree decomposition
-        sage: for node in sorted(label_TD):
+        sage: label_TD.name()
+        'Labelled Nice tree decomposition of Tree decomposition'
+        sage: for node in sorted(label_TD):  # random
         ....:     print(node, label_TD.get_vertex(node))
         (0, {}) forget
         (1, {0}) forget
         (2, {0, 1}) intro
         (3, {0}) forget
-        (4, {0, 4}) join
-        (5, {0, 4}) intro
-        (6, {0, 4}) intro
-        (7, {0}) forget
-        (8, {0}) forget
-        (9, {0, 3}) intro
-        (10, {0, 2}) intro
-        (11, {3}) intro
-        (12, {2}) intro
-        (13, {}) leaf
-        (14, {}) leaf
+        (4, {0, 3}) intro
+        (5, {0}) forget
+        (6, {0, 2}) intro
+        (7, {2}) intro
+        (8, {}) leaf
     """
     from sage.graphs.digraph import DiGraph
     from sage.graphs.graph import Graph
 
     directed_TD = DiGraph(nice_TD.breadth_first_search(start=root, edges=True),
                           format='list_of_edges',
-                          name='Labelled {}'.format(nice_TD))
+                          name='Labelled {}'.format(nice_TD.name()))
 
     # The loop starts from the root node
     # We assume the tree decomposition is valid and nice,