使用 Cerberus 模式自动化文档编制

Question

我们广泛使用 cerberus 来验证 json 配置文件。因此，我们有各种各样的模式，它们定义了这些 json 文档的格式。

我们希望能够使用这些模式为可能需要创建这些 json 文件的用户自动生成一些文档。

目前，我们针对我们拥有的所有不同的配置格式保留单独的文档页面，但是，如果对代码进行的更改未被采纳，则这些文档有时可能会过时，需要更改文档，并且还需要在两个地方更新同一条信息。通过从模式自动生成，文档将始终是最新的并保证反映实际代码，并且可以避免在多个位置进行更新的需要。

我们还使用 Sphinx 根据 .py 文件和单独的 .md 文件中的文档字符串从我们的代码库自动生成文档。

感觉使用 Cerberus 模式文件为每个模式创建“人类可读”文档文件应该相当简单，但我在 Cerberus 或 Sphinx 中找不到任何相关文档。有谁知道这些包中是否有一些本机功能可以实现我所缺少的功能，或者实现此目的的另一种方法或示例？

Answer 1

我也有过类似的想法，不过还没有完全实现。首先，我所做的是使用自定义验证“描述”创建我自己的自定义验证器子类。此验证不执行任何操作，但允许向我的模式添加“描述”字段，我打算稍后将其用于文档目的。

class ConfigValidator(Validator):
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)

def _validate_description(self, constraint:str, field:str, value:str) -> None:
    """
    Enables the use of the key 'description' in schemas in order to add descriptions to fields. Useful for automated documentation in the future. 
    Does no validation.
    
    Args:
        constraint (str): The name constraint applied.
        field (str): The name of the field.
        value (dict): The value of the field.

    The rule's arguments are validated against this schema:
    {'type': 'string'}
    """
    pass