支持json api的文档驱动开发。
docdriven的Python项目详细描述
%docdriven-支持文档驱动开发的python包
%jon crowell
%2013年5月16日
int.首先编写文档，然后从该文档中自动生成测试（由于还没有代码，最初所有测试都将失败），然后编写代码以使测试通过。每次运行测试过程时，它都会通过更新从中派生测试的文档来结束——文档中的每个步骤都会给出一个带有时间戳的状态报告，指示系统是否实际按照文档的方式运行。
n驱动的开发是，将系统的行为与测试该行为分开进行文档记录是没有意义的。测试结果被认为是系统实际行为的"实际文档"，因此文档驱动开发寻求将"实际文档"与发布的文档统一起来。这带来了一个令人高兴的结果，即如果不立即将"红色警报"直接插入到已发布的文档中，则已发布的文档永远不会与其正在编写的代码不同步。它类似于测试驱动的开发，但是它使用了一种编写测试的方法，这种方法依赖于一种有文化的编程技术，其中测试是从文档中提供的合法示例中提取出来的。
文档的发布通过测试文档化的代码，docdriven python包依赖于称为driven down（或documentationdrivendown）的各种标记。这些是扩展名为*.dd的纯文本文件，符合pandoc标记实现，这意味着它们可以很容易地转换为pdf或html文件以及其他格式。（事实上，本文档本身是作为driven down文件编写的。）
drivendown和markdown的关联方式如下：
*以""开头的行在markdown中被视为一级标题，在driven down中被视为一个章节标题。
*以""开头的行是考虑降价时的二级标题和drivendown中的事件标题。（术语"method"、"incident"和"route"在文档驱动的上下文中具有相同的含义——我在谈到测试模块时使用"method"，在谈到通过http测试api时使用"route"（在这种情况下，路由是url），在一般情况下使用"incident"。）以"35;"开头的帽子在降价时被视为四级标题，在drivendown中被视为代码标签。drivendown中目前只允许使用五个代码标签：config、predict、response、runtime和status。"35;pandoc生成的输出，但被drivendown忽略。[todo:请考虑注释的更多内容]
*以四个空格开头的行在标记中被视为代码块，在drivendown中不给予特殊处理，它只是被视为文档自然文本的一部分。
docdriven的测试和文档理论
docdriven包期望项目（或系统/模块/api/任何东西）的文档由一组相关的drivendown文档组成，每个文档都具有以下属性：
1。标题，必须是第一行，并且必须以"%"开头，不能为空。
2。可选的作者/组织信息，必须是e文档，必须以"%"开头。如果不希望包含此信息，则"%"后面的第二行应留空。
3。日期和时间戳必须是第三行，必须以"%"开头，并且不能为空。
<4。可选的介绍章节，标题必须为"介绍"（不区分大小写）。
5。零个或多个章节，每个章节以一级降价标题开头，该标题将成为章节标题。
6。一个可选的结论，必须有标题"结论"。
（即本节）对于全局配置和设置信息，然后处理每个章节（按随机顺序），然后处理结论以进行清理和拆卸。这与标准单元测试框架相对应，这些框架通常有"设置"和"分解"部分，这些部分在测试运行之前和之后运行。
命令，然后是结论。
docdriven方法中的一章既是一个单独的单元测试，也是一个关于一系列相关"事件"的可读故事。（想象一个人讲的是这样一种形式的故事："先发生了这件事，然后发生了那件事，接着又发生了第一件事，接着又发生了另一件事"等等）事件的顺序是有意义的，并且是被保留的。事件可以是一个单独的方法调用，对某个api路由的调用，或者任何其他不同的单元，从广义上来说，接受输入，做某事，并产生输出。
o发生。
事实上，如果一个人想写一章，只包含一个单一的事件，这是合法的。然而，通常一个系统中的几个方法之间有着密切的关系。例如，假设您正在记录一个api，该api提供返回用户id的add_user（username）方法和delete_user（user_id）方法。在添加用户之前，不能删除用户，因此在不首先添加用户的情况下，无法编写delete_user方法的测试。由于这个原因，章节期望一个任意长度的事件列表，它将按顺序执行。
当docdriven处理章节时，它将首先将章节的特定配置信息与引言中提供的全局配置信息合并，然后它将按顺序处理每个事件。处理事件包括将事件的配置信息与本章的一般配置信息合并，然后调用方法，然后将方法返回的响应与文档预测的响应进行比较，最后生成状态报告。
是状态报告吗？
>状态报告是json的一个片段，大致如下：
>>>>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~>"注意"："A shor任意长度的t字符串"
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
状态报告由测试框架生成。代码字可以是总结结果的最多8个字符的任何字符串。例如"blank"、"fail"、"warning"、"success"、"okay"、"http-500"、"http-200"、"unknown"、"works"、"crashed"、"half"、"beginted"等等。当然，它们不一定都是大写的。级别必须是介于0和4之间的数字—对应于成功级别的增加，并且分别对应于蓝色、红色、橙色、黄色和绿色。
=success=green，尽管我经常更改代码词以提供更具体的信息。
如果你愿意的话，可以用粉色、淡紫色和淡紫色来表示。
时间戳只是一个字符串，表示以ISO格式生成状态报告的日期和时间。
您可以随意使用的自由格式字符串字段。但是，请注意，包含包含数百行文本的注释将给系统带来格式化挑战。
在这种特殊情况下，我们正在记录并测试docdriven包本身。为了建立我们的环境，我们需要告诉docdriven在哪里可以找到这个docdriven.dd文件，然后我们将
%jon crowell
%2013年5月16日
int.首先编写文档，然后从该文档中自动生成测试（由于还没有代码，最初所有测试都将失败），然后编写代码以使测试通过。每次运行测试过程时，它都会通过更新从中派生测试的文档来结束——文档中的每个步骤都会给出一个带有时间戳的状态报告，指示系统是否实际按照文档的方式运行。
n驱动的开发是，将系统的行为与测试该行为分开进行文档记录是没有意义的。测试结果被认为是系统实际行为的"实际文档"，因此文档驱动开发寻求将"实际文档"与发布的文档统一起来。这带来了一个令人高兴的结果，即如果不立即将"红色警报"直接插入到已发布的文档中，则已发布的文档永远不会与其正在编写的代码不同步。它类似于测试驱动的开发，但是它使用了一种编写测试的方法，这种方法依赖于一种有文化的编程技术，其中测试是从文档中提供的合法示例中提取出来的。
文档的发布通过测试文档化的代码，docdriven python包依赖于称为driven down（或documentationdrivendown）的各种标记。这些是扩展名为*.dd的纯文本文件，符合pandoc标记实现，这意味着它们可以很容易地转换为pdf或html文件以及其他格式。（事实上，本文档本身是作为driven down文件编写的。）
drivendown和markdown的关联方式如下：
*以""开头的行在markdown中被视为一级标题，在driven down中被视为一个章节标题。
*以""开头的行是考虑降价时的二级标题和drivendown中的事件标题。（术语"method"、"incident"和"route"在文档驱动的上下文中具有相同的含义——我在谈到测试模块时使用"method"，在谈到通过http测试api时使用"route"（在这种情况下，路由是url），在一般情况下使用"incident"。）以"35;"开头的帽子在降价时被视为四级标题，在drivendown中被视为代码标签。drivendown中目前只允许使用五个代码标签：config、predict、response、runtime和status。"35;pandoc生成的输出，但被drivendown忽略。[todo:请考虑注释的更多内容]
*以四个空格开头的行在标记中被视为代码块，在drivendown中不给予特殊处理，它只是被视为文档自然文本的一部分。
docdriven的测试和文档理论
docdriven包期望项目（或系统/模块/api/任何东西）的文档由一组相关的drivendown文档组成，每个文档都具有以下属性：
1。标题，必须是第一行，并且必须以"%"开头，不能为空。
2。可选的作者/组织信息，必须是e文档，必须以"%"开头。如果不希望包含此信息，则"%"后面的第二行应留空。
3。日期和时间戳必须是第三行，必须以"%"开头，并且不能为空。
<4。可选的介绍章节，标题必须为"介绍"（不区分大小写）。
5。零个或多个章节，每个章节以一级降价标题开头，该标题将成为章节标题。
6。一个可选的结论，必须有标题"结论"。
（即本节）对于全局配置和设置信息，然后处理每个章节（按随机顺序），然后处理结论以进行清理和拆卸。这与标准单元测试框架相对应，这些框架通常有"设置"和"分解"部分，这些部分在测试运行之前和之后运行。
命令，然后是结论。
docdriven方法中的一章既是一个单独的单元测试，也是一个关于一系列相关"事件"的可读故事。（想象一个人讲的是这样一种形式的故事："先发生了这件事，然后发生了那件事，接着又发生了第一件事，接着又发生了另一件事"等等）事件的顺序是有意义的，并且是被保留的。事件可以是一个单独的方法调用，对某个api路由的调用，或者任何其他不同的单元，从广义上来说，接受输入，做某事，并产生输出。
o发生。
事实上，如果一个人想写一章，只包含一个单一的事件，这是合法的。然而，通常一个系统中的几个方法之间有着密切的关系。例如，假设您正在记录一个api，该api提供返回用户id的add_user（username）方法和delete_user（user_id）方法。在添加用户之前，不能删除用户，因此在不首先添加用户的情况下，无法编写delete_user方法的测试。由于这个原因，章节期望一个任意长度的事件列表，它将按顺序执行。
当docdriven处理章节时，它将首先将章节的特定配置信息与引言中提供的全局配置信息合并，然后它将按顺序处理每个事件。处理事件包括将事件的配置信息与本章的一般配置信息合并，然后调用方法，然后将方法返回的响应与文档预测的响应进行比较，最后生成状态报告。
是状态报告吗？
>状态报告是json的一个片段，大致如下：
>>>>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~>"注意"："A shor任意长度的t字符串"
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
状态报告由测试框架生成。代码字可以是总结结果的最多8个字符的任何字符串。例如"blank"、"fail"、"warning"、"success"、"okay"、"http-500"、"http-200"、"unknown"、"works"、"crashed"、"half"、"beginted"等等。当然，它们不一定都是大写的。级别必须是介于0和4之间的数字—对应于成功级别的增加，并且分别对应于蓝色、红色、橙色、黄色和绿色。
=success=green，尽管我经常更改代码词以提供更具体的信息。
如果你愿意的话，可以用粉色、淡紫色和淡紫色来表示。
时间戳只是一个字符串，表示以ISO格式生成状态报告的日期和时间。
您可以随意使用的自由格式字符串字段。但是，请注意，包含包含数百行文本的注释将给系统带来格式化挑战。
在这种特殊情况下，我们正在记录并测试docdriven包本身。为了建立我们的环境，我们需要告诉docdriven在哪里可以找到这个docdriven.dd文件，然后我们将
欢迎加入QQ群-->： 979659372
