Artifact-py: 对artifact的重构

注意：这处于alpha阶段。它工作，但可能有很多错误和缺失功能。

这是artifact的Python重构。它将成为将artifact放入构建系统所需的artifact的骨架。没有功能丰富的cli，没有web-ui。只是解析和导出json/markdown等。

同时，这并不是一个严格的重新编写。它是一个重构，并将可能引导artifact 3.0的开发。

使用pip install artifact_py进行安装。它应该在Python 2.7+和3+上工作。

与artifact的差异

主要差异将是

• 用Python而不是Rust编写，以便更容易集成到传统的构建系统中。
• 使用为该项目专门开发的新的anchor_txt markdown属性格式，以避免依赖于任何特定的markdown实现。
• 删除.art/settings.toml，在markdown文件中的任何地方使用属性块替换。
• 命令行工具的极大简化。CLI可能会在未来得到改进。
• 对如何指定和链接工件进行了一些微调，以简化流程。
  • Markdown可以直接在原位置导出 -- 几乎不需要更改文档。
  • 现在通过标题中的锚点来指定工件。通常看起来像这样：# 这是我的规范 (SPC-mine) {#SPC-mine}。其中的{#SPC-mine}是一个（几乎）标准的Markdown锚点，用于创建引用。而(SPC-mine)则是按照惯例设置的，这样人类就可以看到标题正在指定一个工件。
    • 注意：anchor_txt也支持HTML锚点<a id="SPC-mine" />，这是在GitHub中必需的。
  • 使用围栏代码块指定工件属性。参见SPC-design获取示例。
  • 移除了[[REQ-foo]]引用。相反，您只需使用[REQ-foo]或[@REQ-foo]来表示代码。当您运行art export --format md -i时，它们将移除看起来像ART-foo.bar的引用，并在文档底部插入正确的链接。（即[@REQ-foo]: url/to/code.py）
  • 移除了通过[[REQ-foo.subpart]]指定子部分（以前称为子名称）。您只需在属性中指定它们，并使用[@REQ-foo.subpart]在您的文档中链接到代码。
  • 没有对Graphviz提供特殊支持。
  • 不导出工件与Markdown文件的关联关系。在作者看来，这通常只是增加了混乱，并不特别有用。

总的来说，这种设计与标准Markdown规范的结合得更加紧密。它感觉更干净，并允许更轻松地将“任意”设计文档转换为包含丰富链接到源代码和其他设计的文档。

待添加的功能

• 目前只支持单个Markdown文件。我也想在添加更多文件之前重新构思如何集成大量文件等。
• 代码检查 -- 目前没有代码检查器
• 在工件的json中的text字段。它不是任何实现细节所必需的，以后可能会添加。
• 稳定的json输出格式。它仍在变化。

贡献

有关贡献条件，请参阅LICENSE。

代码是用Python编写的。请使用以下方式进行测试

# create the python virtualenv's locally
make init

# run tests against python3
make test3

# run all checks required to ship
make check

设计（SPC-design）

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

所有属性和设置都使用anchor_txt代码块指定。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

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

代码检查（SPC-design.lint）

多项目设计（SPC-design.multi）

单元测试（SPC-design.tst-unittests）

代码： @SPC-design.tst-unittests

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

还进行了测试

• 导出项目结果生成预期的markdown文件

许可证

源代码根据您的选择许可为以下之一

• Apache License，版本2.0，（LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT或https://open-source.org.cn/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}"