如何在GitHub的README.rst中显示literalinclude块

核心原因 #

GitHub采用的Docutils解析器不支持Sphinx专属的literalinclude指令，仅能识别标准reStructuredText语法，导致该块在仓库主页无法正常渲染。

可行解决方案 #

方案1：双版本兼容写法

在README.rst中同时提供Sphinx专属指令和标准代码块，利用Sphinx的条件渲染逻辑实现两边兼容：

# 仅在Sphinx生成文档时渲染literalinclude
.. only:: html
   .. literalinclude:: path/to/your/code.py
      :language: python
      :lines: 1-20

# GitHub会忽略上方的only指令，直接显示标准code-block
.. code-block:: python
   :linenos:

   # 手动同步或通过脚本自动同步代码内容
   def sample_func():
       print("兼容Sphinx和GitHub的代码块")

• 优势：无需额外工具，直接通过语法实现兼容
• 注意：需保持code-block内的代码与目标文件同步，可通过pre-commit钩子脚本自动更新，避免内容不一致

方案2：用脚本自动生成README.rst

编写Python脚本，在提交前自动将目标代码文件内容插入到README.rst的指定位置，替换占位符：

1. 在README.rst中预留占位标记，比如<!-- CODE_BLOCK_PLACEHOLDER -->
2. 脚本读取目标代码文件内容，替换占位符为标准code-block块
3. 将脚本加入pre-commit钩子，每次提交时自动执行

示例脚本逻辑：

with open("path/to/code.py", "r") as f:
    code_content = f.read()

with open("README.rst", "r") as f:
    readme_content = f.read()

updated_readme = readme_content.replace(
    "<!-- CODE_BLOCK_PLACEHOLDER -->",
    f".. code-block:: python\n   :linenos:\n\n{code_content}"
)

with open("README.rst", "w") as f:
    f.write(updated_readme)

• 优势：无需手动同步代码，保证内容一致性
• 注意：需配置pre-commit钩子，确保每次提交前自动执行脚本

方案3：拆分README文件

将仓库主页的说明内容移至README.md（GitHub对Markdown支持更完善），保留README.rst作为Sphinx文档的入口，两者内容按需同步：

• 在Sphinx配置中指定README.rst为文档源
• 仓库主页默认显示README.md，其中用Markdown的代码块展示代码内容

注意事项 #

• 避免在README.rst中过度使用Sphinx专属指令，优先采用标准reStructuredText语法保证跨平台兼容性
• 若使用条件渲染，需测试Sphinx生成效果和GitHub显示效果，确保两边都能正常展示

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