Blueprint-autogenerate-config-tables

• Launchpad 条目: autogenerate-config-tables
• 创建者: Tom Fifield
• 贡献者: Steven Deaton

总结

开发一个系统，根据代码自动创建配置选项表格，并保持更新。

这将确保配置选项引用始终正确，并减少文档团队有限成员所需的工作量。

原理

目前，手册中的配置选项表格是手动编写和更新的。这导致

• 延迟更新配置选项
• 由于手动性质导致更新不正确
• 效率低下，因为在大多数情况下，这些选项直接来自代码。

设计

该系统

1. “解析” {nova, swift, quantum, cinder, glance, keystone} 的代码，以确定当前的配置选项、默认值和帮助文本
2. 输出如下 docbook 表格格式
3. 创建/更新包含表格选项的文件
4. 向 Gerrit 发送包含更改文件的评审

文件格式

 <?xml version="1.0" encoding="UTF-8"?>
 <para xmlns= "http://docbook.org/ns/docbook" version= "5.0"> 
  <table rules= "all">
     <caption>Description of nova.conf file configuration options
         for sectiopn</caption>
     <col width= "50%"/>
     <col width= "50%"/>
     <thead>
         <tr>
             <td><para>Configuration option=Default value</para></td>
             <td><para>(Type) Description</para></td>
         </tr>
     </thead>
     <tbody>
         <tr>
             <td><para> option_name=default_value </para></td>
             <td><para> (TypeOpt) Description text goes here</para></td>
         </tr>
         ... 
         more table rows here
          ...
           </tbody>
 </table>
 </para>

问题

• 配置表格的文档更新将被覆盖
  • 然后应在各自的代码项目中对配置变量的文本描述进行更改，这也有助于提高 CLI 描述的质量。
• 代码中配置选项的划分方式与书籍中的划分方式不同
• 代码中的配置选项不一定与示例配置文件中的配置选项匹配
• 默认值并不总是位于选项声明中，而可以在代码的其他地方找到

---