This demonstration of part of compliance-trestle. It is designed to demonstrate trestle author a set of functionality designed to support automation for content created, typically in a source code repository.
For this demonstration trestle author docs and trestle author folders is used. These functions are used to validate (individual documents, and folders of documents, respectively), markdown files against a template. The template is enforced based on the heading structure. For more information see the trestle website.
arc42 is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. The arc42 files in this repository have been modified for use within this demo. If you need arc42 content please go here.
This repository has been setup with three trestle author tasks:
arc42-single- Demonstrating use of trestle to validate the single file templatearc42-multidoc- Demonstrating the use of trestle to validate a cohesive set of documentsarc42-single-failure- intentionally demonstrating failure.
This demo is at two levels:
- The first is the setup instructions below. The setup instructions for these three workflows shows how to create a 'new' file(s) for editing using
trestle author {docs|folders} create sample - The second is the repository has been setup with Github actions. Github actions calls
trestle author {docs|folders} validatevia a Makefile to act as a CI validation (e.g. before merging content).- Note: Github actions has been configured to allow validation failure of the
arc42-single-failuretask.
- Note: Github actions has been configured to allow validation failure of the
-
trestle initwas run inside the repository -
OSCAL model directories, unnecessary for this demo, were removed (see issue to resolve)
-
trestle author docs setup -tn arc42-singlewas run to setup for the single file architecture template- The arc42 github template was downloaded
- The template file was copied to the template file
- The template was customized by 'commenting out' where the template provided exemplar headings (exemplar headings can not be enforced with trestle author).
trestle author docs create-sample -tn arc42-singletrestle author docs validate -tn arc42-singlewas called for testing the template / instance- The sample was edited.
trestle author docs validate -tn arc42-singlewas called to validate the setup.
-
trestle author folders setup -tn arc42-multidocwas run to setup for multiple file setups.- The arc42 github template was downloaded.
- The template file was copied to the template file
- As with the single file content that was not appropriate for trestle author templates was commented out.
- Note for MD format HTML comment lines must not be the last line in the file (there should be one blank line)
trestle author folders create-sample -tn arc42-multidocto create a sample- Sample was edited.
trestle author folders validate -tn arc42-multidoc
-
trestle author docs setup -tn arc42-single-failurewas run to setup for the single file architecture template where it would fail validaation- The arc42 github template was downloaded
- The template file was copied to the template file
- The template was customized by 'commenting out' where the template provided exemplar headings (exemplar headings can not be enforced with trestle author).
trestle author docs create-sample -tn arc42-singletrestle author docs validate -tn arc42-singlewas called for testing the template / instance- The sample was edited in a way designed to intentionally break the template. E.g. a required heading in the template was removed.
trestle author docs validate -tn arc42-singlewas called to validate the setup and ensure a failure condition was reached.