From eed5861884738f23c5a90066088598587f41b199 Mon Sep 17 00:00:00 2001 From: Louis Burke Date: Mon, 1 May 2023 12:39:30 -0400 Subject: [PATCH] Added summary document --- Jenkinsfile | 17 ++++++++++++ Makefile | 23 ++++++++-------- README.md | 18 +++++------- build/.gitkeep | 0 docs/flit-begin.tex | 1 + docs/flit-footer.tex | 1 + docs/flit-leader.tex | 12 ++++++++ docs/flit.css | 5 ++++ docs/summary.mmd | 65 ++++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 120 insertions(+), 22 deletions(-) create mode 100644 Jenkinsfile create mode 100644 build/.gitkeep create mode 100644 docs/flit-begin.tex create mode 100644 docs/flit-footer.tex create mode 100644 docs/flit-leader.tex create mode 100644 docs/flit.css create mode 100644 docs/summary.mmd diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 0000000..f7058ea --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,17 @@ +pipeline { + agent any + + stages { + stage('Documentation') { + steps { + sh 'make docs' + } + } + stage('Deploy') { + steps { + archiveArtifacts artifacts: 'build/*.pdf', fingerprint: true + archiveArtifacts artifacts: 'build/*.html', fingerprint: true + } + } + } +} diff --git a/Makefile b/Makefile index e4fd80f..7eeb13a 100644 --- a/Makefile +++ b/Makefile @@ -12,26 +12,27 @@ VERSION=$(LAST_TAG:v%=%)$(PATCH)$(DIRTY) default: all # List of documents to produce from markdown -DOCUMENTS=README - -HTML_DOCS=$(patsubst %,%.html,$(DOCUMENTS)) -PDF_DOCS=$(patsubst %,%.pdf,$(DOCUMENTS)) +DOCUMENTS=$(wildcard docs/%.mmd) +HTML_DOCS=$(patsubst docs/%.mmd,build/%.html,$(DOCUMENTS)) +PDF_DOCS=$(patsubst docs/%.mmd,build/%.pdf,$(DOCUMENTS)) all: docs docs: $(HTML_DOCS) $(PDF_DOCS) -%.html: %.md - sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -t html > $@ +build/%.html: docs/%.mmd + sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -thtml > $@ -%.pdf: %.md - sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -t latex > $*.tex - pdflatex $*.tex - pdflatex $*.tex - -rm $*.aux $*.toc $*.log $*.tex $*.out +build/%.pdf: docs/%.mmd + sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -tlatex > build/$*.tex + pdflatex -output-directory=build -interaction=batchmode build/$*.tex + pdflatex -output-directory=build -interaction=batchmode build/$*.tex + -rm $*.aux $*.toc $*.log build/$*.tex $*.out clean: -rm $(HTML_DOCS) $(PDF_DOCS) print-%: @echo '$*: $($*)' + +# Project-level note: mmd files can have comments via ```{=comment} ... or {=todo} diff --git a/README.md b/README.md index 7e2dd15..36bf1d2 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,8 @@ -vi: spell:spelllang=en:tw=72 -Author: Louis A. Burke -Affiliation: labprogramming.net -Title: FLIT -- README -CSS: ./flit.css -Language: en -LaTeX Leader: flit-leader.tex -LaTeX Begin: flit-begin.tex -LaTeX Footer: flit-footer.tex -LaTeX Header Level: 3 +# Four-Letter Interleaved T(est/ask) Protocol -# Four-Letter Interleaved T(ask/est) Protocol +FLIT is a protocol for test reporting. + + +## License + +This project is [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) licensed. diff --git a/build/.gitkeep b/build/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/flit-begin.tex b/docs/flit-begin.tex new file mode 100644 index 0000000..0a6cf14 --- /dev/null +++ b/docs/flit-begin.tex @@ -0,0 +1 @@ +\begin{document} diff --git a/docs/flit-footer.tex b/docs/flit-footer.tex new file mode 100644 index 0000000..6b47932 --- /dev/null +++ b/docs/flit-footer.tex @@ -0,0 +1 @@ +\end{document} diff --git a/docs/flit-leader.tex b/docs/flit-leader.tex new file mode 100644 index 0000000..a015c1a --- /dev/null +++ b/docs/flit-leader.tex @@ -0,0 +1,12 @@ +\documentclass{article} + +\usepackage{hyperref} +\usepackage{tabularx} +\usepackage{tabulary} +\usepackage{booktabs} +\usepackage[normalem]{ulem} +\usepackage{glossaries} +\usepackage{soul} + +\setcounter{secnumdepth}{0} +%\renewcommand{\chapternumberline}[1]{}% Gobble chapter numbers in TOC diff --git a/docs/flit.css b/docs/flit.css new file mode 100644 index 0000000..6942278 --- /dev/null +++ b/docs/flit.css @@ -0,0 +1,5 @@ +code { + font-size: 12pt; + font-weight: bold; + color: darkblue; +} diff --git a/docs/summary.mmd b/docs/summary.mmd new file mode 100644 index 0000000..7d69cba --- /dev/null +++ b/docs/summary.mmd @@ -0,0 +1,65 @@ +--- +vi: spell:spelllang=en:tw=72:ft=markdown +Author: Louis A. Burke +Affiliation: labprogramming.net +Title: FLIT -- Summary +CSS: docs/flit.css +Language: en +LaTeX Leader: docs/flit-leader.tex +LaTeX Begin: docs/flit-begin.tex +LaTeX Footer: docs/flit-footer.tex +LaTeX Header Level: 3 +--- + +# Four-Letter Interleaved T(ask/est) Protocol + +Version: **%VERSION%** + +{{TOC}} + +--- + +## Comparison with popular test formats + +| Feature | FLIT | [TAP14] | [Robot] | [xUnit] | +| :----------------------- | :--------: | :--------: | :--------: | :--------: | +| [Concurrent] | {++YES++} | {--NO--} | {++YES++} | {++YES++} | +| [Language Agnostic] | {++YES++} | {++YES++} | {++NO++} | {++YES++} | +| [Human-Readable] | {++YES++} | {++YES++} | {==SOME==} | {--NO--} | +| [Hierarchical] | {++YES++} | {--NO--} | {++YES++} | {==SOME==} | + +### Concurrent + +FLIT supports concurrent test execution by allowing outputs for multiple +tests to be interleaved without loss of information. TAP14, by contrast, +requires that all test outputs occur in order. Robot and xUnit both +support concurrent tests, though they don't necessarily display partial +results accurately in such cases. + +### Language Agnostic + +FLIT is a text-based, line oriented protocol that can be implemented +easily in most programming languages, similarly to TAP14. xUnit is also +a mostly language agnostic system, though its protocol is not as simple. +Robot framework generates its own report format from robot files. Custom +reporters can be implemented in Python or Java, but not arbitrary +languages. + +### Human Readable + +FLIT output is human readable, though perhaps not as readable as some +other formats. On the other hand, Robot and xUnit outputs require +further processing or tools (such as web browsers) to view properly. + +### Hierarchical + +FLIT tests can be nested as deeply as desired. This is common to most +test frameworks to some degree. However, they often do not properly +treat nested tests within steps correctly. In particular, TAP14 does not +support the type of nested sub-steps that make Robot tests so easy to +debug. + +[>FLIT]: Four-Letter Interleaved T(est/ask) +[TAP14]: https://testanything.org/tap-version-14-specification.html +[Robot]: https://robotframework.org/ +[xUnit]: https://junit.org/junit5/