适配新版Sphinx/dot：修复Python浅拷贝可视化GraphViz代码

问题概述 #

维护一门多年的Python课程，文档基于Sphinx构建。升级到Sphinx 9.0.1（搭配GraphViz dot 2.44.0）后，用于讲解别名与浅拷贝的digraph可视化代码出现兼容性错误，需保留原布局（变量x、y居左，整体垂直紧凑）。

原预期图形结构 #

x → [ | | ]
         /  |  \
        /   |   \
       /    |    \
      ↙︎     ↓     ↘︎
[1|2|3]  [4|5|6]  [7|8|9]
      ↖︎     ↑     ↗︎
       \    |    /
        \   |   /
         \  |  /
     y → [ | | ]

对应Python示例代码 #

x = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
y = list(x)
y = x.copy()  # equivalent
y = x[:]      # equivalent

原报错的GraphViz代码 #

.. digraph:: alias_3

    node [colorscheme=pastel28, fillcolor=1, style=filled];
    { node[shape=box, fillcolor=2];
      x; y;
    }
    { node[shape=record, fillcolor=3];
      list123 [label="1|2|3"];
      list456 [label="4|5|6"];
      list789 [label="7|8|9"];
      listX [label="<1>|<2>|<3>"];
      listY [label="<1>|<2>|<3>"];
    }
    subgraph { rank=same; x -> listX; }
    subgraph { rank=same; y -> listY; }
    listX:1 -> list123;
    listX:2 -> list456;
    listX:3 -> list789;
    list123 -> listY:1 [dir=back];
    list456 -> listY:2 [dir=back];
    list789 -> listY:3 [dir=back];

报错信息 #

Warning: flat edge between adjacent nodes one of which has a record shape - replace records with HTML-like labels
Edge x -> listX
Error: lost x listX edge
Error: lost y listY edge

兼容修复方案 #

可以实现，核心修改是将record形状替换为HTML-style标签，同时调整rank控制逻辑以适配新版dot的布局规则：

修改后的GraphViz代码 #

.. digraph:: alias_3

    node [colorscheme=pastel28, fillcolor=1, style=filled];
    # 变量节点（x、y）
    { node[shape=box, fillcolor=2];
      x; y;
    }
    # 列表节点，改用HTML标签替代record
    { node[shape=none, fillcolor=3, label=<
        <table border="0" cellborder="1" cellspacing="0">
            <tr><td port="1">1</td><td port="2">2</td><td port="3">3</td></tr>
        </table>>];
      list123;
    }
    { node[shape=none, fillcolor=3, label=<
        <table border="0" cellborder="1" cellspacing="0">
            <tr><td port="1">4</td><td port="2">5</td><td port="3">6</td></tr>
        </table>>];
      list456;
    }
    { node[shape=none, fillcolor=3, label=<
        <table border="0" cellborder="1" cellspacing="0">
            <tr><td port="1">7</td><td port="2">8</td><td port="3">9</td></tr>
        </table>>];
      list789;
    }
    # x和y指向的空列表容器
    { node[shape=none, fillcolor=3, label=<
        <table border="0" cellborder="1" cellspacing="0">
            <tr><td port="1"></td><td port="2"></td><td port="3"></td></tr>
        </table>>];
      listX; listY;
    }
    # 控制同一水平层级
    { rank=same; x; listX; }
    { rank=same; y; listY; }
    # 连接边
    x -> listX;
    y -> listY;
    listX:1 -> list123:1;
    listX:2 -> list456:2;
    listX:3 -> list789:3;
    listY:1 -> list123:1 [dir=back];
    listY:2 -> list456:2 [dir=back];
    listY:3 -> list789:3 [dir=back];

修改说明 #

1. 替换record为HTML标签：新版dot对record形状的相邻flat edge（如x到listX的直接连接）兼容性变差，改用HTML表格标签可避免该警告和丢边错误。
2. 调整rank控制：将原subgraph内的rank控制改为直接在rank=same组中包含变量和容器节点，布局逻辑更清晰，适配新版dot的rank计算规则。
3. 明确端口连接：HTML节点的端口通过<td port="xxx">定义，边连接时指定端口确保指向正确位置，保持原图形的引用关系。

简化替代方案（可选） #

如果追求更简洁的代码，可合并相同样式的节点定义，同时用分组进一步优化布局：

.. digraph:: alias_3
    rankdir=TB;
    node [colorscheme=pastel28, fillcolor=1, style=filled];

    # 变量组
    { node[shape=box, fillcolor=2]; x; y; }
    # 中间列表组（同一水平层级）
    { rank=same;
      node[shape=none, fillcolor=3];
      list123 [label=<
          <table border="0" cellborder="1" cellspacing="0"><tr><td>1</td><td>2</td><td>3</td></tr></table>>];
      list456 [label=<
          <table border="0" cellborder="1" cellspacing="0"><tr><td>4</td><td>5</td><td>6</td></tr></table>>];
      list789 [label=<
          <table border="0" cellborder="1" cellspacing="0"><tr><td>7</td><td>8</td><td>9</td></tr></table>>];
    }
    # 容器组（x、y指向的空列表）
    { node[shape=none, fillcolor=3, label=<
        <table border="0" cellborder="1" cellspacing="0"><tr><td port="1"></td><td port="2"></td><td port="3"></td></tr></table>>];
      listX; listY;
    }

    # 控制变量与容器的水平对齐
    rank=same; x -> listX;
    rank=same; y -> listY;

    # 连接引用关系
    listX:1 -> list123;
    listX:2 -> list456;
    listX:3 -> list789;
    listY:1 -> list123 [dir=back];
    listY:2 -> list456 [dir=back];
    listY:3 -> list789 [dir=back];

内容的提问来源于stack exchange，提问作者ShadowRanger