sphinx-gherkindoc 3.2.6

我为什么要用它？

与更大的团队分享您的需求。 小黄瓜使任何人都能很容易地阅读需求。 狮身人面像使小黄瓜足够漂亮，可读性。 sphinx-gherkindoc处理转换纯文本功能文件 变成易于阅读的文档，你不会畏缩不前地与更大的团队分享。

轻松查看您有哪些步骤以及在哪里使用它们。sphinx-gherkindoc可以创建步骤的词汇表。 这有助于您轻松地：

• find steps to reuse
• notice similar steps that might be duplicates or unintended variations
• see patterns that you might exploit to reduce the number of steps you have
• find out where and which feature files would be affected if a step’s wording or implementation changes

怎么做到的？

sphinx-gherkindoc递归地扫描给定的目录 要查找所有要素和标记文件， 把它们转换成文件 可以包含在基于sphinx的文档中。 这个脚本的灵感来自sphinx-apidoc 对源代码也有类似的作用。

有关命令行选项的特定详细信息， 请查阅--help输出。 大多数命令行选项在sphinx-apidoc中镜像它们的对应项。

对于最基本的用法，输入（<gherkin_path>） 必须提供输出（<output_path>）路径。 放入^{tt9}的文件$ 可以合并到任何更大的文档中， 以任何方式创造。

此外，还可以添加与fnmatch兼容的模式列表 到命令行， 指示要从处理中排除的目录。

一个值得注意的补充是step词汇表（-G，--step-glossary）。 step glossary命令行选项导致sphinx-gherkindoc 在<output_path>目录中创建命名文件。 步骤词汇表内容格式化为两个列表：

• A list of all the steps found, in alphabetical order. Each item in this list is a link to its details in the second list.
• A list of the steps showing the file names and line numbers where they are used. This list is in order by the most number of uses first.

如何转换我的文件？

扫描<gherkin_path>目录树时， sphinx-gherkindoc将执行以下操作：

• Feature files found are processed into rST files in the ^{tt9}$ directory.
• Directories will be converted to Sphinx Table of Contents (TOC) files that link to any feature files in the same directory, and to any TOC files from direct subdirectories.
• Any rST files found in a directory have their contents copied to the front of the TOC file for that directory. If more than one rST file is found in a directory, they are processed in sort order.
• If no rST files are found in a directory, then a header for the TOC is created based on the contents of a ^{tt19}$ file, if present, or the name of the directory.
• Any MarkDown (md) files are referenced from the TOC file for the directory they are in.
• Directories with no feature, rST, or md files are pruned, recursively upwards.

肉馅土豆将是你的特色文件。 将rst文件放在功能文件旁边 提供上下文和其他有用的材料。 如果有任何rst文件在同一目录中， 它们还应该包含任何适当的标题 以及其他类似的格式。 sphinx-gherkindoc只有在 根本不存在RST文件。

示例

免责声明：这不是如何使用或配置sphinx的教程。 它是可以使用^{tt1}的一些常见方法$ 作为文档生成的一部分。 如果你跳过以上所有内容，请提醒： --help将显示默认值 不使用命令行选项时。

惯例-基于sphinx的文档生成通常使用两个目录：

• ^{tt23}$ - the working directory where we put all the rST files from the various tools as we are building documents. This directory shoud not be checked in to version control and should only contain files created by a documentation run.
• ^{tt24}$ - the output directory for a documentation run. For example, this is where ^{tt25}$ is found when building HTML docs, etc. This directory should not be checked in to version control as it contains only derived and processed files.

1. 将特征文件转换为RST； 处理所有功能和文档文件 在feature/root/directory-here目录中/在_docs目录下 使用所有默认值：

   sphinx-gherkindoc feature/root/directory-here _docs
   

2. 同上， 还要在_docs中创建一个步骤词汇表文件my_step_glossary：

   sphinx-gherkindoc -G my_step_glossary feature/root/directory-here _docs
   

三。实验！ 一旦你有第二步工作 并集成到您的文档构建过程中， 你可能会发现你想调整一些结果。 在基本流程运行之后，这样做要容易得多。 试验其他可选参数 得到你想要的效果。

标记链接的特殊说明

任何标记都可以转换为匿名链接 通过插件或命令行参数。 转换器必须是单一功能 它接受一个字符串参数，标记， 如果标记应该包含一个链接，则返回一个url 或者是空字符串。

为了注册基于poetry的项目的插件：

[tools.poetry.plugins."parsers"]
url = "my_custom_library.parse:optional_url_from_tag"

为了注册基于setup.py的项目的插件：

setup(
    ...
    entry_points={
        'parsers': ['url = my_custom_library.parse:optional_url_from_tag']
    }
)

为了通过命令行使用解析器， 应该使用--url_from-tag标志。提供的字符串应格式化为<library>:<method_name>