Sphinx中如何用only指令实现可选列表项？

你原来的写法会因为only指令打断列表结构，导致生成多个独立的<ul>标签。要让所有列表项处于同一个<ul>里，需要让可选列表项成为原列表的一部分，而非插入独立的块结构。

正确写法示例 #

将only指令嵌套在列表项内部，把可选内容作为该列表项的条件显示内容：

foo bar:

- a
- b
- .. only:: Internal

     c
- d

当Internal构建条件满足时，会显示包含c的列表项；不满足时，该列表项会被隐藏，其余列表项仍保持在同一个<ul>标签中，不会出现拆分的情况。

如果需要让- c作为完全独立的列表项（而非某列表项的条件内容），可以调整缩进层级，让only块与前后列表项保持同一层级，同时确保only块内的列表项缩进正确：

foo bar:

- a
- b
.. only:: Internal

   - c
- d

这种写法需要注意：部分reStructuredText解析器可能仍会拆分列表，因此更推荐第一种嵌套在列表项内的写法。

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