如何在Sphinx中使用literalinclude访问Linux系统绝对路径？

需求背景 #

想用Sphinx记录Ubuntu系统的各类修改（网络配置、Apache站点配置、自定义脚本等），希望通过literalinclude直接访问系统根目录的文件，类似Windows中直接使用绝对路径的方式，但担心直接链接根目录会导致Sphinx遍历整个系统，寻求可行方案。

可行实现方法 #

1. 直接使用绝对路径+配置排除目录 #

Sphinx的literalinclude本身支持绝对路径，无需额外创建符号链接。只需在Sphinx配置文件conf.py中添加exclude_patterns，排除系统中无需遍历的动态/临时目录，即可避免全系统遍历：

# conf.py 配置示例
exclude_patterns = [
    '/proc/**',
    '/sys/**',
    '/dev/**',
    '/tmp/**',
    '/var/log/**'
    # 根据需求添加其他不需要的系统目录
]

之后在rst文件中直接引用系统绝对路径：

.. literalinclude:: /etc/apache2/sites-available/000-default.conf
   :language: apache
   :linenos:
   :start-after: # Custom Config Start
   :end-before: # Custom Config End
   :emphasize-lines: 5-8

2. 仅创建目标文件/目录的符号链接 #

不要直接链接整个系统根目录，只针对需要记录的具体文件或目录创建符号链接，既满足路径引用需求，又不会引入冗余目录：

# 在Sphinx的source目录下创建存放链接的文件夹
mkdir -p source/system_configs
# 链接Apache配置文件
ln -s /etc/apache2/sites-available/000-default.conf source/system_configs/apache_default.conf
# 链接自定义脚本
ln -s /usr/local/bin/my_setup_script.sh source/system_configs/setup_script.sh

在rst文件中使用相对路径引用：

.. literalinclude:: system_configs/setup_script.sh
   :language: bash
   :linenos:
   :start-after: # LOG START
   :end-before: # LOG END

3. 定义路径变量简化引用 #

在conf.py中定义常用系统路径的变量，或在rst文件中直接设置路径替换，让引用更简洁易维护：

• 方式一（rst内直接定义替换）：

.. |apache_conf_path| replace:: /etc/apache2/sites-available/

.. literalinclude:: |apache_conf_path|000-default.conf
   :language: apache
   :linenos:

• 方式二（conf.py全局配置）：

# conf.py中添加
def setup(app):
    app.add_config_value('apache_conf', '/etc/apache2/sites-available/', 'env')

然后在rst中通过模板变量引用（需配合Sphinx的模板功能）。

额外注意事项 #

• 权限问题：部分系统配置文件需要root权限才能读取，可先将文件复制到Sphinx目录下（如source/backup_configs），再引用复制后的文件，避免构建时权限不足。
• 跨环境一致性：如果需要在多台机器上构建文档，绝对路径可能存在差异，此时使用符号链接或复制文件的方式更可靠。

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