如何记录配置文件？答案

【问题标题】：How to document config files?如何记录配置文件？
【发布时间】：2019-07-26 09:15:23
【问题描述】：

配置文件文档是否有任何最佳实践，尤其是对于 python？

特别是在科学计算中，通常使用配置文件作为输入来控制批处理作业（例如模拟），并期望用户为他们的场景定制大部分配置。（配置也可能在不同的处理模块中进行选择，每个模块拥有不同的配置字段套件。）因此，用户应该知道：每个设置的含义或效果；哪些设置未使用（在哪些情况下）；什么是默认值（以及允许的值或范围）；等等。

我发现不完整的配置文件文档很常见。根本问题似乎是，如果文档与代码分开维护，它们就会变得不同步。（这对于 API 文档来说似乎不太成问题，因为标准做法涉及并置文档字符串和从函数签名/argspec 自动生成。）例如，如果使用标准 python configparser 一次来解析配置文件，那么访问单个属性的代码（并隐式确定配置模式）可能仍然分布在整个代码库中（并且可能仅在运行时可用，而不是在构建文档时可用）。

进一步的想法：

将配置文件（yaml 或类似文件）替换为用户自定义的 python 脚本（以便只需要 API 文档）是不好的做法吗？
一个注释良好的示例配置文件的分发（也用于自动测试）：如果不同的场景重复大的部分但需要一些完全不同的字段，如何维护？
是否可以维护一个模式，既可用于代码（帮助解析、验证和设置默认值），也可用于以某种方式生成文档？
是否有一种人类可读/可写的方式来（反）序列化表示新批处理过程的某些（子）类实例的状态（以便现有文档涵盖配置）？

【问题讨论】：

标签： python configuration documentation maintainability

【解决方案1】：

就个人而言，我喜欢使用argparse 模块进行配置，并从环境变量中读取每个设置的默认值。这将设置和文档集中在一个地方，并允许用户在命令行上调整设置或在环境变量中设置并忘记它们。不过，在命令行中输入密码时要小心，因为其他用户可能会在进程列表中看到您的命令行参数。

这是使用argparse 和环境变量的an example：

def parse_args(argv=None):
    parser = ArgumentParser(description='Watch the raw data folder for new runs.',
                            formatter_class=ArgumentDefaultsHelpFormatter)
    parser.add_argument(
        '--kive_server',
        default=os.environ.get('MICALL_KIVE_SERVER', 'http://localhost:8000'),
        help='server to send runs to')
    parser.add_argument(
        '--kive_user',
        default=os.environ.get('MICALL_KIVE_USER', 'kive'),
        help='user name for Kive server')
    parser.add_argument(
        '--kive_password',
        default=SUPPRESS,
        help='password for Kive server (default not shown)')

    args = parser.parse_args(argv)
    if not hasattr(args, 'kive_password'):
        args.kive_password = os.environ.get('MICALL_KIVE_PASSWORD', 'kive')
    return args

设置这些环境变量可能有点混乱，尤其是对于系统服务。如果您使用的是 systemd，请查看 service unit，并小心使用 EnvironmentFile 而不是 Environment 来获取任何秘密。任何使用systemctl show 的用户都可以查看Environment 值。

我通常使默认值对在他们的工作站上运行的开发人员有用，这样他们就可以在不更改任何配置的情况下开始开发。

另一种选择是将配置设置放在settings.py 文件中，并注意不要将该文件提交到源代码管理。我经常提交用户可以复制的settings_template.py 文件。

如果您的设置非常复杂/灵活，以至于环境变量或设置文件变得混乱，那么我会将项目转换为带有 API 的库。然后用户编写一个调用您的 API 的脚本，而不是设置。您也不必费力在 PyPI 上托管您的库。例如，pip 可以从 GitHub repository 安装。

【讨论】：