Package: artifact-py
Artifact-py: a reimagining ofartifactNOTICE: this is in alpha. It works but likely has many bugs and missing
features.This is a reimplementation ofartifactin python. It will be the barebones of
artifact necessary to put it in a build system. No featureful cli, no web-ui.
Just parsing and exporting of json/markdown/etc.At the same time, this is not a strict rewrite. It is a reimagining and will
probably guide the development of artifact 3.0.Install withpip install artifact_py. It should work in python 2.7+ and 3+Differences withartifactThe primary differences will be:Written in python instead of rust for easier inclusion in legacy build
systems.The use of the newanchor_txtmarkdown attribute format, developed
specifically for this project to not have dependencies on any specific
markdown implementation.Removal of.art/settings.toml, replaced with an attribute block anywhere in
the markdown file.Massive simplification of the cmdline tool. The CLI may be improved in the future.A few minor tweaks to simplify how artifacts are specified and linked.Markdown can be exportedin place-- almost none of the document has to
be changed.Artifacts are now specified by the anchor in a header. Conventionally it
will look like# This is my spec (SPC-mine) {#SPC-mine}. The{#SPC-mine}is a (not-quite) standard markdown anchor used to create a
reference. The(SPC-mine)is by-convention so that humans can see that
the header is specifying an artifact.Note:anchor_txtalso supported the html anchor<a id="SPC-mine" />,
which is what is necessary in githubArtifact attributes are specified with a fenced code block. SeeSPC-designfor an example.Removal of[[REQ-foo]]references. Instead you just use[REQ-foo]or[@REQ-foo]for code.
When you runart export --format md -ithey will strip out references that look likeART-foo.barand insert the correct links at the bottom of your document.
(i.e.[@REQ-foo]: url/to/code.pyRemoval of specifying subparts (formerly called subnames) via[[REQ-foo.subpart]]. Simply specify them in your attributes with partof,
and link to the code in your deisign doc with[@REQ-foo.subpart].Has no special support for graphviz.No exporting of the relationship of artifacts to the markdown file itself.
In the author's opinion this frequently just added to clutter and was not
especially useful.Overall, this design works much more hand-in-hand with the standard markdown
specification. Itfeelscleaner, and allows for easier conversion from an
"arbitrary" design document to one that is rich in links to source code and
other designs.Features still to be added:Currently only supports a single markdown file. I also want to re-imagine how large
numbers of files/etc could be integrated before adding more files.Linting -- no linter currently existstextfield in the json of artifact. It was not required for any implementation details
and may be added later.A stable json output format. It is still in flux.ContributingSeeLICENSEfor conditions of contributions.Code is in python. Test using the following:# create the python virtualenv's locally
make init

# run tests against python3
make test3

# run all checks required to ship
make checkDesign (SPC-design)subparts:-artifact-settings-code-lint-tst-unittestsAll attributes and settings are specified with ananchor_txtcode block.Settings are specified like this, anywhere in the document:```yaml @
artifact:
  root_dir: ./
  code_paths:
    - src/
```Artifact attributes like this:```yaml @
partof:
  - SPC-other

subparts:
  - function
  - tst-unit
```Settings (SPC-design.settings)code:@SPC-design.settingsArtifacts are injected from the--docmarkdown design document. All
settings/attributes are provided using theanchor_txtformat. Settings
are provided by adding the following to anartifactattribute anywhere
in the document:root_dir: the root directory when creating paths. This will affect
where other path settings use as a reference.code_paths: paths to files or directories to look for code.
SeeCode Linksfor more information.exclude_code_paths: paths to exclude when searching for artifacts.Artifact (SPC-design.artifact)code:@SPC-design.artifactAn artifact is a piece of documentation that can be linked to other pieces of
documentation and to source code. It has the following attributes:name: defines how it can be linked. The name is defined in the
anchor header ({#REQ-foo})There are three types of artifacts: REQ (requirement), SPC (specification),
TST (test)partof: the other artifacts this artifact is a partof.subparts: pieces of an artifact that can be linked in code.done: force an artifact to be considered specified and testedCode Links (SPC-design.code)code:@SPC-design.codeArtifacts are linked in code by:Defining an artifact name or subpartSpecifyingcode_pathsinSettingsPutting a tag anywhere in code of the form:#SPC-foo#SPC-foo.barArtifact will run a regular expression over all files found incode_pathsand
will mark artifacts as specified/tested if they are linked in code.Lints (SPC-design.lint)Note: This is not yet implementedcode: [@SPC-design.lint]The lint command will find errors in the design document, and how it is
reflected in the code:partoflinks that do not exist.AREQorSPCbeingpartofaTSTExtraimpllinks in codeHaving an artifact specified as "done" having an implArtifact or subpart like links in text (i.e.[REQ-does-not-exist]) that do
not exist.Design docs not being updated (runartifact export --format md -ito fix).A link being found in code that does not have thedoc_urlprefixed.
(i.e. artifact expects links in code to look likemyurl.com/design#REQ-foo)Multi-project designs (SPC-design.multi)Not yet implemented, design phase onlycode: [@SPC-design.multi]Artifact's previous design fell short of supporting multiple different designs,
especially at scale. This rewrite/reimainging immagines the following principles:Designs for a "module/package/submodule/etc" are contained within a single file.
This links to a "small" amount of source code for that design and are specified
in theartifactattribute in that file.Linking to other design files can be done via a "references" object in the settings.
They are specified likeother_design: path/to/other/fileInline links will then be auto-generated so that you can use[other_design#SPC-foo]to link to other documents.Specified and tested ratios are not affected by these links.Because the designs are onlylinkedtogether (not dependent on eachother for
completion ratios), each design can be calculated independently and it's
metadata serialized so that other projects can link to it.Unit Tests (SPC-design.tst-unittests)code:@SPC-design.tst-unittestsThe unit tests offer almost complete coverage. Nearly all of the features
are tested using a data-driven approach. There is a markdown file, with
a yaml file of the same name. The yml file has the expected value after
parsing the markdown file.Also tested:That exporting the project results in the expected markdown fileLicenseThe source code is Licensed under either ofApache License, Version 2.0, (LICENSE-APACHEorhttp://www.apache.org/licenses/LICENSE-2.0)MIT license (LICENSE-MITorhttp://opensource.org/licenses/MIT)at your option.Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.Metadataartifact:root_dir:'./'code_paths:-artifact_py/-tests/exclude_code_paths:-tests/artifacts_only/-tests/projects/-tests/test_code.pycode_url:"https://github.com/vitiral/artifact_py/blob/master/{file}#L{line}"