Artifact-py：对工件的重新构想

注意：这是 alpha 版本。它可以工作，但可能有很多错误和缺失的功能。

这是在 python中对工件的重新实现。它将是将其放入构建系统所必需的工件的准系统。没有特色 cli，没有 web-ui。只是解析和导出 json/markdown/etc。

同时，这不是严格的重写。这是一个重新构想，可能会指导工件 3.0 的开发。

安装pip install artifact_py。它应该在 python 2.7+ 和 3+ 中工作

与神器的区别

主要区别在于：

• 用 python 而不是 rust 编写，以便更容易地包含在遗留构建系统中。
• 使用专门为此项目开发的新的anchor_txt降价属性格式，不依赖于任何特定的降价实现。
• 删除.art/settings.toml, 替换为 markdown 文件中任意位置的属性块。
• cmdline 工具的大量简化。将来可能会改进 CLI。
• 一些小的调整以简化工件的指定和链接方式。
  • Markdown 可以就地导出——几乎不需要更改任何文档。
  • 工件现在由标头中的锚指定。按照惯例，它看起来像# This is my spec (SPC-mine) {#SPC-mine}. 这 {#SPC-mine}是一个（不完全）标准的降价锚，用于创建参考。这(SPC-mine)是约定俗成的，因此人们可以看到标头正在指定工件。
    • 注意：anchor_txt还支持 html 锚点<a id="SPC-mine" />，这是 github 中必须的
  • 工件属性是用围栏代码块指定的。 有关示例，请参见SPC 设计。
  • 删除[[REQ-foo]]参考。相反，您只需将[REQ-foo]or[@REQ-foo]用于代码。当您运行时，art export --format md -i 它们会删除看起来像 的引用ART-foo.bar并在文档底部插入正确的链接。（IE[@REQ-foo]: url/to/code.py
  • 通过 删除指定的子部分（以前称为子名） [[REQ-foo.subpart]]。只需使用 partof 在您的属性中指定它们，并使用 链接到您的设计文档中的代码[@REQ-foo.subpart]。
  • 对 graphviz 没有特别的支持。
  • 没有将工件的关系导出到降价文件本身。在作者看来，这经常只是增加了混乱，并不是特别有用。

总体而言，这种设计与标准降价规范更紧密地结合在一起。它感觉更干净，并且可以更轻松地将“任意”设计文档转换为包含丰富的源代码和其他设计链接的文档。

仍有待添加的功能：

• 目前仅支持单个 markdown 文件。我还想重新想象在添加更多文件之前可以集成多少文件/等。
• Linting - 当前不存在 linter
• text工件的 json 中的字段。任何实现细节都不需要它，以后可能会添加。
• 稳定的 json 输出格式。它仍在不断变化。

贡献

请参阅许可证以了解供款条件。

代码在python中。使用以下方法进行测试：

# create the python virtualenv's locally
make init

# run tests against python3
make test3

# run all checks required to ship
make check

设计（SPC-设计）

subparts:
  - artifact
  - settings
  - code
  - lint
  - tst-unittests

所有属性和设置都使用anchor_txt代码块指定。

设置是这样指定的，在文档的任何地方：

```yaml @
artifact:
  root_dir: ./
  code_paths:
    - src/
```

工件属性如下：

```yaml @
partof:
  - SPC-other

subparts:
  - function
  - tst-unit
```

设置（SPC-design.settings）

代码：@SPC-design.settings

--doc工件是从Markdown 设计文档中注入的。所有设置/属性均使用anchor_txt格式提供。通过将以下内容添加到artifact文档中任意位置的属性来提供设置：

• root_dir: 创建路径时的根目录。这将影响其他路径设置用作参考的位置。
• code_paths: 用于查找代码的文件或目录的路径。有关详细信息，请参阅代码链接。
• exclude_code_paths：搜索工件时要排除的路径。

工件（SPC-design.artifact）

代码：@SPC-design.artifact

工件是可以链接到其他文档和源代码的文档。它具有以下属性：

• name: 定义如何链接。名称在锚标头 ( {#REQ-foo}) 中定义
  • 工件分为三类：REQ（要求）、SPC（规范）、TST（测试）
• partof：此工件所属的其他工件。
• subparts：可以在代码中链接的工件的片段。
• done: 强制一个工件被认为是指定和测试的

代码链接 (SPC-design.code)

代码：@SPC-design.code

工件在代码中通过以下方式链接：

• 定义工件名称或子部分
• code_paths在设置中指定
• 在表单代码中的任何位置放置标签：
  • #SPC-foo
  • #SPC-foo.bar

Artifact 将对在其中找到的所有文件运行正则表达式，code_paths如果它们在代码中链接，则会将工件标记为指定/测试。

皮棉 (SPC-design.lint)

多项目设计 (SPC-design.multi)

单元测试 (SPC-design.tst-unittests)

代码：@SPC-design.tst-unittests

单元测试提供了几乎完整的覆盖。几乎所有功能都使用数据驱动的方法进行测试。有一个markdown文件，有一个同名的yaml文件。yml文件解析markdown文件后有预期值。

还测试了：

• 导出项目会产生预期的降价文件

执照

源代码已获得许可

• Apache 许可证，版本 2.0，（LICENSE-APACHE或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT 许可证（LICENSE-MIT或 http://opensource.org/licenses/MIT）

由您选择。

除非您另有明确说明，否则按照 Apache-2.0 许可中的定义，您有意提交以包含在工作中的任何贡献均应如上所述获得双重许可，而无需任何附加条款或条件。

元数据

artifact:
  root_dir: './'

  code_paths:
    - artifact_py/
    - tests/

  exclude_code_paths:
    - tests/artifacts_only/
    - tests/projects/
    - tests/test_code.py

  code_url:
    "https://github.com/vitiral/artifact_py/blob/master/{file}#L{line}"