diff options
| -rw-r--r-- | CONTRIBUTING | 289 | ||||
| l--------- | CONTRIBUTING.rst | 1 | ||||
| -rw-r--r-- | Makefile | 64 | ||||
| -rw-r--r-- | README | 163 | ||||
| l--------- | README.rst | 1 | ||||
| -rw-r--r-- | doc/Dockerfile | 21 | ||||
| -rw-r--r-- | doc/Makefile | 19 | ||||
| -rw-r--r-- | doc/source/_static/css/custom.css | 16 | ||||
| -rw-r--r-- | doc/source/_static/swagger/.swagger-codegen-ignore | 23 | ||||
| -rw-r--r-- | doc/source/_static/swagger/.swagger-codegen/VERSION | 1 | ||||
| -rw-r--r-- | doc/source/_static/swagger/index.html | 746 | ||||
| -rw-r--r-- | doc/source/api.txt | 7 | ||||
| -rw-r--r-- | doc/source/conf.py | 176 | ||||
| -rw-r--r-- | doc/source/creating-job.txt | 152 | ||||
| -rw-r--r-- | doc/source/dependencies.txt | 53 | ||||
| -rw-r--r-- | doc/source/index.txt | 23 | ||||
| -rw-r--r-- | doc/source/readme.txt | 1 |
17 files changed, 1748 insertions, 8 deletions
diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..5283d76 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,289 @@ +############ +Contributing +############ + +.. contents:: Table of Contents + +We use `Github`_ for managing code and issues and `GerritHub`_ for reviews. + +.. _GerritHub: https://review.gerrithub.io/admin/projects/SamsungSLAV/weles +.. _Github: https://github.com/SamsungSLAV/weles + + +***************** +How to contribute +***************** + +Reporting bugs +============== + +Create issue on `GitHub`_. + +Suggesting enhancements +======================= + +Create issue on `GitHub`_. + +Code contributions +================== + +Check issues on `Github`_. + +*********** +Styleguides +*********** + +Git +=== + +Commit message +-------------- + +Check following articles regarding commit messages: + +- `Tim Pope's blog post`_ +- `Chris Beams blog post`_ + +Each commit message must be signed-off. This means that the contributor agrees +to `Developer Certificate of Origin`_. + +If committer will not be responsive but his patch will be chosen to be merged, +some fixes might be added by someone else. Signoff will show original author +even when someone else will commit it. + +.. _`Tim Pope's blog post`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +.. _`Chris Beams blog post`: https://chris.beams.io/posts/git-commit +.. _`Developer Certificate of Origin`: https://developercertificate.org/ + + +Commit size +----------- + +Each feature should be on its designated branch. This allows to divide features +into small commits which are easier to review. + +Branching schema +---------------- + +Main branches +^^^^^^^^^^^^^ + +Currently there is one main branch: ``master``. + +Feature branches +^^^^^^^^^^^^^^^^ + +Feature branches should be named uniquely and identify the feature developed. + +Merge strategy +^^^^^^^^^^^^^^ + +Feature branches are always merged without fast-forwarding to keep branch +information. + +Release strategy +---------------- + +Releases are flagged on master branch using git tag. We use `Semantic +Versioning 2.0`_ . + +.. _`Semantic Versioning 2.0`: https://semver.org/ + +Coding style +============ + +Automatic formatters +-------------------- + +We use both gofmt_ and goimports_. It is recommended to set your editor to run those two on save. +It is desired to place internal SLAV imports at the bottom. + +.. _goimports: https://godoc.org/golang.org/x/tools/cmd/goimports + +Line breaks +----------- + +Breaking lines on 100 chars +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The goal of this rule is to have code easy to read on vertical monitor or two files on a horizontal +monitor. + +We consider tab to be 4 chars. + +Breaking function signature when parameter list goes over 100 chars +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + + // Having a function signature like this, where the paginator weles.ArtifactPagination parameter + // exceeds the 100 chars: here: v + func (aDB *ArtifactDB) Filter(filter weles.ArtifactFilter, sorter weles.ArtifactSorter, paginator weles.ArtifactPagination) ([]weles.ArtifactInfo, weles.ListInfo, error) { + results := []weles.ArtifactInfo{} + ... + } + + // You should change it to: + func (aDB *ArtifactDB) Filter(f weles.ArtifactFilter, s weles.ArtifactSorter, + p weles.ArtifactPagination) ([]weles.ArtifactInfo, weles.ListInfo, error) { + + results := []weles.ArtifactInfo{} + ... + } + // Please remember to add new line between functon signature and body to indicate end of function + // signature. This is because gofmt indents them to the same level. + +Breaking function signature when return goes over 100 chars +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + + // Having a function signature like this, where *Downloader return parameter exceeds + // 100 chars: here: v + func newDownloader(notification chan weles.ArtifactStatusChange, workers, queueSize int) *Downloader { + return newDownloader(notification, workerCount, queueCap) + } + // You should change it to + func NewDownloader(notification chan weles.ArtifactStatusChange, workerCount, queueCap int, + ) *Downloader { + return newDownloader(notification, workerCount, queueCap) + } + // Please note lack of new line between function signature and body. They have different + // indentation level thus new line is not necessary. + +Breaking a struct literal when it goes over 100 chars +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + + // Having a line like below: + f := weles.JobFilter{CreatedAfter: strfmt.DateTime(magicDate), CreatedBefore: strfmt.DateTime{}} + // You should change it to: + f := weles.JobFilter{ + CreatedAfter: strfmt.DateTime(magicDate), + CreatedBefore: strfmt.DateTime{}, + } // Note the comma in previous line and the closing brace in new line. + +Tests +----- + +We use Ginkgo_ which is BDD-style Go testing framework with Gomega_ which is a +matcher library. + +.. _Ginkgo: https://onsi.github.io/ginkgo/ +.. _Gomega: https://github.com/onsi/gomega + +Static Analysis +--------------- + +We use `gometalinter`_ to check the code. To use locally, please download .v2 +version and execute it in Weles repository root (or pass .gometalinter.json +explicitly) Below table contains overview of the checkers used in Weles. +Automatically generated code is not subject to static analysis. + ++---------------------------+-------------------------------------------------------------------------------+ +| Linter | Description | ++===========================+===============================================================================+ +| deadcode_ | Find unused code | ++---------------------------+-------------------------------------------------------------------------------+ +| errcheck_ | Check that error return values are used. | ++---------------------------+-------------------------------------------------------------------------------+ +| goconst_ | Finds repeated strings that could be replaced by a constant. | ++---------------------------+-------------------------------------------------------------------------------+ +| gocyclo_ | Computes the cyclomatic complexity of functions. | +| | | +| | Max cyclomatic complexity: 15 | ++---------------------------+-------------------------------------------------------------------------------+ +| gofmt_ | Checks if the code is properly formatted and could not be further simplified. | ++---------------------------+-------------------------------------------------------------------------------+ +| golint_ | Google's (mostly stylistic) linter. | ++---------------------------+-------------------------------------------------------------------------------+ +| `gosec (previously gas)`_ | Inspects source code for security problems by scanning the Go AST. | ++---------------------------+-------------------------------------------------------------------------------+ +| gosimple_ | Report simplifications in code. | ++---------------------------+-------------------------------------------------------------------------------+ +| ineffassign_ | Detect when assignments to existing variables are not used. | ++---------------------------+-------------------------------------------------------------------------------+ +| interfacer_ | Suggest narrower interfaces that can be used. | ++---------------------------+-------------------------------------------------------------------------------+ +| lll_ | Report long lines. | +| | | +| | Max line length: 100. Tab width: 4. | ++---------------------------+-------------------------------------------------------------------------------+ +| maligned_ | Detect structs that would take less memory if their fields were sorted. | ++---------------------------+-------------------------------------------------------------------------------+ +| megacheck_ | Run staticcheck_, gosimple_ and unused_, sharing work. | ++---------------------------+-------------------------------------------------------------------------------+ +| staticcheck_ | Statically detect bugs, both obvious and subtle ones. | ++---------------------------+-------------------------------------------------------------------------------+ +| structcheck_ | Find unused struct fields. | ++---------------------------+-------------------------------------------------------------------------------+ +| unconvert_ | Detect redundant type conversions. | ++---------------------------+-------------------------------------------------------------------------------+ +| unparam_ | Find unused function parameters. | ++---------------------------+-------------------------------------------------------------------------------+ +| unused_ | Find `unused variables`_. | ++---------------------------+-------------------------------------------------------------------------------+ +| varcheck_ | Find unused global variables and constants. | ++---------------------------+-------------------------------------------------------------------------------+ +| vet_ | Reports potential errors that otherwise compile. | ++---------------------------+-------------------------------------------------------------------------------+ +| vetshadow_ | Reports variables that may have been unintentionally shadowed. | ++---------------------------+-------------------------------------------------------------------------------+ + +.. _gometalinter: https://github.com/alecthomas/gometalinter> +.. _deadcode: https://github.com/tsenart/deadcode +.. _errcheck: https://github.com/kisielk/errcheck +.. _goconst: https://github.com/jgautheron/goconst +.. _gocyclo: https://github.com/alecthomas/gocyclo +.. _gofmt: https://golang.org/cmd/gofmt +.. _golint: https://github.com/golang/lint +.. _`gosec (previously gas)`: https://github.com/securego/gosec +.. _gosimple: https://github.com/dominikh/go-tools/tree/master/cmd/gosimple +.. _ineffassign: https://github.com/gordonklaus/ineffassign +.. _interfacer: https://github.com/mvdan/interfacer +.. _lll: https://github.com/walle/lll +.. _maligned: https://github.com/mdempsky/maligned +.. _megacheck: https://github.com/dominikh/go-tools/tree/master/cmd/megacheck +.. _staticcheck: https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck +.. _structcheck: https://github.com/opennota/check +.. _unconvert: https://github.com/mdempsky/unconvert +.. _unparam: https://github.com/mvdan/unparam +.. _unused: https://github.com/dominikh/go-tools/tree/master/cmd/unused +.. _`unused variables`: https://github.com/dominikh/go-tools/tree/master/cmd/unused#what-counts-as-usedunused +.. _varcheck: https://github.com/opennota/check +.. _vet: https://golang.org/cmd/vet +.. _vetshadow: https://golang.org/cmd/vet/#hdr-Shadowed_variables + +Documentation styleguide +======================== + +All documentation parts are gathered into Sphinx documentation. + +User Documentation +------------------ + +For Sphinx documentation we follow `Benoit Bryon's styleguide`_. + +Non Sphinx rst documents (such as README, CONTRIBUTING) follow only rules +listed below + +* Whitespaces +* Line length (where possible) +* Headings + +.. _`Benoit Bryon's styleguide`: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html + +API Documentation +----------------- + +API Documentation is prepared according to `OpenAPI 2.0`_. + +.. _`OpenAPI 2.0`: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md + +Code Documentation +------------------ + +Currently Godoc is not used. It will be included in Sphinx documentation in +later stages of the project. + diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 120000 index 0000000..73dfc33 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1 @@ +CONTRIBUTING
\ No newline at end of file @@ -17,6 +17,14 @@ SERVER_BIN = $(BIN_DIR)/weles BUILD_DOCKER_IMAGE = weles-build-img BUILD_DOCKER_CONTAINER = weles-build +DOC_DIR = doc +SPHINX_DOCKER_IMAGE = weles-doc-image +SPHINX_DOCKER_CONTAINER = weles-doc-container +SPHINX_DOCKER_CONTAINER_WORKDIR = /doc +SWAGGER_DOCKER_IMAGE = swaggerapi/swagger-codegen-cli +SWAGGER_DOCKER_CONTAINER = weles-swagger-container +SWAGGER_DOCKER_CONTAINER_WORKDIR = /local + .PHONY: all all: docker-build @@ -75,18 +83,58 @@ swagger-models-generate: swagger.yml COPYING -s ./server \ -r ./COPYING \ -.PHONY: swagger-docs-html -swagger-docs-html: swagger.yml - mkdir -p doc/build/swagger +.PHONY: docs +docs: docs-swagger docs-sphinx + +.PHONY: clean-docs +clean-docs: clean-docs-swagger clean-docker-swagger clean-docs-sphinx clean-docker-sphinx + +.PHONY: docs-sphinx +docs-sphinx: docker-image-sphinx docker run \ --rm \ - -v $$PWD:/local \ - --user `id -u $$USER`:`id -g $$USER` \ - swaggerapi/swagger-codegen-cli \ + --volume "`pwd`:${SPHINX_DOCKER_CONTAINER_WORKDIR}" \ + --user "`id -u $$USER`:`id -g $$USER`" \ + --name "${SPHINX_DOCKER_CONTAINER}" "${SPHINX_DOCKER_IMAGE}" \ + make -C "${SPHINX_DOCKER_CONTAINER_WORKDIR}/${DOC_DIR}" html + +.PHONY: docker-image-sphinx +docker-image-sphinx: + docker build -t "${SPHINX_DOCKER_IMAGE}" ${DOC_DIR} + +.PHONY: clean-docs-sphinx +clean-docs-sphinx: + -rm -r "${DOC_DIR}/build" + +.PHONY: clean-docker-sphinx +clean-docker-sphinx: + -docker rm "${SPHINX_DOCKER_CONTAINER}" + -docker rmi "${SPHINX_DOCKER_IMAGE}" + +# docs-swagger generates API documentation in HTML format, to be used by +# Sphinx. +.PHONY: docs-swagger +docs-swagger: swagger.yml + mkdir -p ${DOC_DIR}/source/_static/swagger + docker run \ + --rm \ + -v "`pwd`:${SWAGGER_DOCKER_CONTAINER_WORKDIR}" \ + --user "`id -u $$USER`:`id -g $$USER`" \ + --name "${SWAGGER_DOCKER_CONTAINER}" \ + "${SWAGGER_DOCKER_IMAGE}"\ generate \ - -i local/swagger.yml \ + -i "${SWAGGER_DOCKER_CONTAINER_WORKDIR}/swagger.yml" \ -l html \ - -o /local/doc/build/swagger/ + -o "${SWAGGER_DOCKER_CONTAINER_WORKDIR}/${DOC_DIR}/source/_static/swagger/" + +.PHONY: clean-docs-swagger +clean-docs-swagger: + -rm -rf doc/source/_static/swagger + +.PHONY: clean-docker-swagger +clean-docker-swagger: + -docker rm "${SWAGGER_DOCKER_CONTAINER}" + -docker rmi "${SWAGGER_DOCKER_IMAGE}" vendor: Gopkg.lock dep ensure -v -vendor-only @@ -0,0 +1,163 @@ +##### +Weles +##### + +******** +Overview +******** + +Weles is part of SLAV_ stack. It is a simple, lightweight generic test framework. +It uses Boruta_ for DUT [#]_ reservation and MuxPi_ for accessing it. +Weles was inspired by LAVA_. + +Weles responsibilities include: + +* acquiring DUT from Boruta_ system +* flashing images to the DUT +* running tests +* presenting results in a human and computer-readable form + +.. [#] Device Under Test +.. _MuxPi: https://github.com/SamsungSLAV/muxpi +.. _Boruta: https://github.com/SamsungSLAV/boruta +.. _SLAV: https://github.com/SamsungSLAV/slav +.. _LAVA: https://www.linaro.org/initiatives/lava/ + +User provides a yaml file containing all neccessary information to perform tests: + +* required capabilities of a target device +* timeouts +* priority +* interface for accessing target +* credentials, input sequences +* test cases to be run defined as a list of: + + * commands for target + * files to be pushed to target + * artifacts to be collected from a target + +Check sample yaml for Weles in parser/sample_yaml + + +************* +Documentation +************* + +`Weles documentation`_ is hosted on Read The Docs pages. + +.. _`Weles documentation`: https://weles.rtfd.io/ + + +********** +Deployment +********** + +Docker +====== + +Prerequisites + +* Docker_ +* Make_ + +.. _Docker: https://www.docker.com/ +.. _Make: https://www.gnu.org/software/make/ + + +Clone Weles and go to that directory:: + + $ git clone https://github.com/SamsungSLAV/weles.git && cd weles + +Adjust swagger.yml to your instance. You should only edit following fields: + +* description +* termsOfService +* contact +* host + +And build Weles:: + + $ make docker-build + +Local +===== + +- git +- make +- `go (1.10+)`_ + +.. _`go (1.10+)`: https://golang.org/doc/install + + +Go get it and go to weles directory:: + + $ go get github.com/SamsungSLAV/weles + $ cd $GOPATH/src/github.com/SamsungSLAV/weles + +Weles uses Dep to manage dependencies; if you dont have it, go get it:: + + $ go get -u github.com/golang/dep/cmd/dep + +Download all dependencies:: + + $ make vendor + +Adjust swagger.yml to your instance. You should only edit following fields: + +* description +* termsOfService +* contact +* host + +Regenerate server code with your changes in the swagger.yml file:: + + $ make swagger-server-generate + +And finally we can build Weles:: + + $ make server + +The binary of Weles will be available in bin/weles-server + +Run it with -h flag:: + + $ bin/weles-server -h + +to receive full list of parameters. + + +*********** +Using Weles +*********** + +Currently server supports only http protocol. +Following flags may be ignored: + +- --tls* +- --scheme +- --socket-path + +When you run your server, you can check the API documentation on http://host:port/api/v1/docs/ +Remember to set `--boruta-address` flag with proper Boruta address or Weles won't work! + + +Contact information +=================== + ++----------------------+----------------------------------+ +| Name | E-mail | ++======================+==================================+ +| Paweł Wieczorek | p.wieczorek2@samsung.com | ++----------------------+----------------------------------+ +| Łukasz Wojciechowski | l.wojciechow@partner.samsung.com | ++----------------------+----------------------------------+ + + +******* +License +******* + +Weles is distributed under `Apache 2.0 License`_ + +.. _`Apache 2.0 License`: LICENSE + diff --git a/README.rst b/README.rst new file mode 120000 index 0000000..100b938 --- /dev/null +++ b/README.rst @@ -0,0 +1 @@ +README
\ No newline at end of file diff --git a/doc/Dockerfile b/doc/Dockerfile new file mode 100644 index 0000000..d2ad2f5 --- /dev/null +++ b/doc/Dockerfile @@ -0,0 +1,21 @@ +FROM alpine:3.8 +LABEL maintainer="Michal Sidor <m.sidor@samsung.com>" + +ENV PLANTUML_VERSION 1.2018.8 + +RUN mkdir -p /opt/plantuml \ + && wget https://sourceforge.net/projects/plantuml/files/plantuml.${PLANTUML_VERSION}.jar/download -O /opt/plantuml/plantuml.jar +RUN apk --no-cache add python3 make openjdk8-jre-base graphviz ttf-freefont \ + libjpeg-turbo zlib tiff \ + && apk --no-cache add -t .makedepends libjpeg-turbo-dev zlib-dev tiff-dev \ + python3-dev build-base +RUN pip3 install --upgrade pip setuptools \ + && pip3 install 'Pillow >=5.2.0,<5.3' 'Sphinx >=1.8.0,<1.9' \ + 'sphinxcontrib-plantuml ==0.11' 'sphinxcontrib-actdiag >=0.8.0,<0.9' \ + 'sphinxcontrib-blockdiag >=1.5.0,<1.6' 'sphinxcontrib-seqdiag >=0.8.0,<0.9' \ + && apk --no-cache del .makedepends + +ENV DATA_DIR=/doc JAVA_HOME=/usr/lib/jvm/java-1.8-openjdk + +WORKDIR $DATA_DIR +VOLUME $DATA_DIR diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..69fe55e --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css new file mode 100644 index 0000000..0bc0cdb --- /dev/null +++ b/doc/source/_static/css/custom.css @@ -0,0 +1,16 @@ +.up { + float:right; + font-size: 15px; + font-family: Trebuchet MS, sans-serif; + padding: 14px; +} + +.method-path { + font-size: 1.5em; + background-color: #10a54a !important; +} + +.huge { + color: #fff; + background-color: #10a54a !important; +} diff --git a/doc/source/_static/swagger/.swagger-codegen-ignore b/doc/source/_static/swagger/.swagger-codegen-ignore new file mode 100644 index 0000000..c5fa491 --- /dev/null +++ b/doc/source/_static/swagger/.swagger-codegen-ignore @@ -0,0 +1,23 @@ +# Swagger Codegen Ignore +# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell Swagger Codgen to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/doc/source/_static/swagger/.swagger-codegen/VERSION b/doc/source/_static/swagger/.swagger-codegen/VERSION new file mode 100644 index 0000000..855ff95 --- /dev/null +++ b/doc/source/_static/swagger/.swagger-codegen/VERSION @@ -0,0 +1 @@ +2.4.0-SNAPSHOT
\ No newline at end of file diff --git a/doc/source/_static/swagger/index.html b/doc/source/_static/swagger/index.html new file mode 100644 index 0000000..6e5d050 --- /dev/null +++ b/doc/source/_static/swagger/index.html @@ -0,0 +1,746 @@ +<!doctype html> +<html> + <head> + <title>Weles</title> + <style type="text/css"> + body { + font-family: Trebuchet MS, sans-serif; + font-size: 15px; + color: #444; + margin-right: 24px; +} + +h1 { + font-size: 25px; +} +h2 { + font-size: 20px; +} +h3 { + font-size: 16px; + font-weight: bold; +} +hr { + height: 1px; + border: 0; + color: #ddd; + background-color: #ddd; +} + +.app-desc { + clear: both; + margin-left: 20px; +} +.param-name { + width: 100%; +} +.license-info { + margin-left: 20px; +} + +.license-url { + margin-left: 20px; +} + +.model { + margin: 0 0 0px 20px; +} + +.method { + margin-left: 20px; +} + +.method-notes { + margin: 10px 0 20px 0; + font-size: 90%; + color: #555; +} + +pre { + padding: 10px; + margin-bottom: 2px; +} + +.http-method { + text-transform: uppercase; +} + +pre.get { + background-color: #0f6ab4; +} + +pre.post { + background-color: #10a54a; +} + +pre.put { + background-color: #c5862b; +} + +pre.delete { + background-color: #a41e22; +} + +.huge { + color: #fff; +} + +pre.example { + background-color: #f3f3f3; + padding: 10px; + border: 1px solid #ddd; +} + +code { + white-space: pre; +} + +.nickname { + font-weight: bold; +} + +.method-path { + font-size: 1.5em; + background-color: #0f6ab4; +} + +.up { + float:right; +} + +.parameter { + width: 500px; +} + +.param { + width: 500px; + padding: 10px 0 0 20px; + font-weight: bold; +} + +.param-desc { + width: 700px; + padding: 0 0 0 20px; + color: #777; +} + +.param-type { + font-style: italic; +} + +.param-enum-header { +width: 700px; +padding: 0 0 0 60px; +color: #777; +font-weight: bold; +} + +.param-enum { +width: 700px; +padding: 0 0 0 80px; +color: #777; +font-style: italic; +} + +.field-label { + padding: 0; + margin: 0; + clear: both; +} + +.field-items { + padding: 0 0 15px 0; + margin-bottom: 15px; +} + +.return-type { + clear: both; + padding-bottom: 10px; +} + +.param-header { + font-weight: bold; +} + +.method-tags { + text-align: right; +} + +.method-tag { + background: none repeat scroll 0% 0% #24A600; + border-radius: 3px; + padding: 2px 10px; + margin: 2px; + color: #FFF; + display: inline-block; + text-decoration: none; +} + + </style> + </head> + <body> + <h1>Weles</h1> + <div class="app-desc">This is a Weles server. You can find out more about Weles at <a href="http://tbd.tbd">http://tbd.tbd</a>.</div> + <div class="app-desc">More information: <a href="https://helloreverb.com">https://helloreverb.com</a></div> + <div class="app-desc">Contact Info: <a href="tbd@tbd.com">tbd@tbd.com</a></div> + <div class="app-desc">Version: 0.0.0</div> + <div class="app-desc">BasePath:/api/v1</div> + <div class="license-info">Apache 2.0</div> + <div class="license-url">http://www.apache.org/licenses/LICENSE-2.0.html</div> + <h2>Access</h2> + + <h2><a name="__Methods">Methods</a></h2> + [ Jump to <a href="#__Models">Models</a> ] + + <h3>Table of Contents </h3> + <div class="method-summary"></div> + <h4><a href="#Artifacts">Artifacts</a></h4> + <ul> + <li><a href="#artifactLister"><code><span class="http-method">post</span> /artifacts/list</code></a></li> + </ul> + <h4><a href="#Jobs">Jobs</a></h4> + <ul> + <li><a href="#jobCanceler"><code><span class="http-method">post</span> /jobs/{JobID}/cancel</code></a></li> + <li><a href="#jobCreator"><code><span class="http-method">post</span> /jobs</code></a></li> + <li><a href="#jobLister"><code><span class="http-method">post</span> /jobs/list</code></a></li> + </ul> + + <h1><a name="Artifacts">Artifacts</a></h1> + <div class="method"><a name="artifactLister"/> + <div class="method-path"> + <a class="up" href="#__Methods">Up</a> + <pre class="post"><code class="huge"><span class="http-method">post</span> /artifacts/list</code></pre></div> + <div class="method-summary">List artifacts with filter and sort features (<span class="nickname">artifactLister</span>)</div> + <div class="method-notes">ArtifactLister returns information on filtered Weles artifacts.</div> + + + <h3 class="field-label">Consumes</h3> + This API call consumes the following media types via the <span class="header">Content-Type</span> request header: + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Request body</h3> + <div class="field-items"> + <div class="param">artifactFilterAndSort <a href="#ArtifactFilterAndSort">ArtifactFilterAndSort</a> (optional)</div> + + <div class="param-desc"><span class="param-type">Body Parameter</span> — Artifact Filter and Sort object. </div> + + </div> <!-- field-items --> + + + <h3 class="field-label">Query parameters</h3> + <div class="field-items"> + <div class="param">after (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — ID of the last element from previous page. format: int64</div><div class="param">before (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — ID of first element from next page. format: int64</div><div class="param">limit (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — Custom page limit. Denotes number of ArtifactInfo structures that will be returned. format: int32</div> + </div> <!-- field-items --> + + + <h3 class="field-label">Return type</h3> + <div class="return-type"> + array[<a href="#ArtifactInfo">ArtifactInfo</a>] + + </div> + + <!--Todo: process Response Object and its headers, schema, examples --> + + <h3 class="field-label">Example data</h3> + <div class="example-data-content-type">Content-Type: application/json</div> + <pre class="example"><code>[ "", "" ]</code></pre> + + <h3 class="field-label">Produces</h3> + This API call produces the following media types according to the <span class="header">Accept</span> request header; + the media type will be conveyed by the <span class="header">Content-Type</span> response header. + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Responses</h3> + <h4 class="field-label">200</h4> + OK + + <h4 class="field-label">206</h4> + Partial Content + + <h4 class="field-label">400</h4> + Bad Request + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">404</h4> + Not Found + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">500</h4> + Internal Server error + <a href="#ErrResponse">ErrResponse</a> + </div> <!-- method --> + <hr/> + <h1><a name="Jobs">Jobs</a></h1> + <div class="method"><a name="jobCanceler"/> + <div class="method-path"> + <a class="up" href="#__Methods">Up</a> + <pre class="post"><code class="huge"><span class="http-method">post</span> /jobs/{JobID}/cancel</code></pre></div> + <div class="method-summary">Cancel existing job (<span class="nickname">jobCanceler</span>)</div> + <div class="method-notes">JobCanceler stops execution of Job identified by JobID.</div> + + <h3 class="field-label">Path parameters</h3> + <div class="field-items"> + <div class="param">JobID (required)</div> + + <div class="param-desc"><span class="param-type">Path Parameter</span> — format: uint64</div> + </div> <!-- field-items --> + + <h3 class="field-label">Consumes</h3> + This API call consumes the following media types via the <span class="header">Content-Type</span> request header: + <ul> + <li><code>application/json</code></li> + </ul> + + + + + + + <!--Todo: process Response Object and its headers, schema, examples --> + + + <h3 class="field-label">Produces</h3> + This API call produces the following media types according to the <span class="header">Accept</span> request header; + the media type will be conveyed by the <span class="header">Content-Type</span> response header. + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Responses</h3> + <h4 class="field-label">204</h4> + No Content + <a href="#"></a> + <h4 class="field-label">403</h4> + Forbidden + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">404</h4> + Not Found + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">500</h4> + Internal Server error + <a href="#ErrResponse">ErrResponse</a> + </div> <!-- method --> + <hr/> + <div class="method"><a name="jobCreator"/> + <div class="method-path"> + <a class="up" href="#__Methods">Up</a> + <pre class="post"><code class="huge"><span class="http-method">post</span> /jobs</code></pre></div> + <div class="method-summary">Add new job (<span class="nickname">jobCreator</span>)</div> + <div class="method-notes">adds new Job in Weles using recipe passed in YAML format.</div> + + + <h3 class="field-label">Consumes</h3> + This API call consumes the following media types via the <span class="header">Content-Type</span> request header: + <ul> + <li><code>multipart/form-data</code></li> + </ul> + + + + + <h3 class="field-label">Form parameters</h3> + <div class="field-items"> + <div class="param">yamlfile (required)</div> + + <div class="param-desc"><span class="param-type">Form Parameter</span> — is Job description yaml file. </div> + </div> <!-- field-items --> + + <h3 class="field-label">Return type</h3> + <div class="return-type"> + <a href="#JobID">JobID</a> + + </div> + + <!--Todo: process Response Object and its headers, schema, examples --> + + <h3 class="field-label">Example data</h3> + <div class="example-data-content-type">Content-Type: application/json</div> + <pre class="example"><code>{ }</code></pre> + + <h3 class="field-label">Produces</h3> + This API call produces the following media types according to the <span class="header">Accept</span> request header; + the media type will be conveyed by the <span class="header">Content-Type</span> response header. + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Responses</h3> + <h4 class="field-label">201</h4> + Created + <a href="#JobID">JobID</a> + <h4 class="field-label">415</h4> + Unsupported media type + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">422</h4> + Unprocessable entity + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">500</h4> + Internal Server error + <a href="#ErrResponse">ErrResponse</a> + </div> <!-- method --> + <hr/> + <div class="method"><a name="jobLister"/> + <div class="method-path"> + <a class="up" href="#__Methods">Up</a> + <pre class="post"><code class="huge"><span class="http-method">post</span> /jobs/list</code></pre></div> + <div class="method-summary">List jobs with filter and sort features (<span class="nickname">jobLister</span>)</div> + <div class="method-notes">JobLister returns information on filtered Weles Jobs.</div> + + + <h3 class="field-label">Consumes</h3> + This API call consumes the following media types via the <span class="header">Content-Type</span> request header: + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Request body</h3> + <div class="field-items"> + <div class="param">jobFilterAndSort <a href="#JobFilterAndSort">JobFilterAndSort</a> (optional)</div> + + <div class="param-desc"><span class="param-type">Body Parameter</span> — Job Filter and Sort object. </div> + + </div> <!-- field-items --> + + + <h3 class="field-label">Query parameters</h3> + <div class="field-items"> + <div class="param">after (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — JobID of the last element from previous page. format: uint64</div><div class="param">before (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — JobID of first element from next page. format: uint64</div><div class="param">limit (optional)</div> + + <div class="param-desc"><span class="param-type">Query Parameter</span> — Custom page limit. Denotes number of JobInfo structures that will be returned. format: int32</div> + </div> <!-- field-items --> + + + <h3 class="field-label">Return type</h3> + <div class="return-type"> + array[<a href="#JobInfo">JobInfo</a>] + + </div> + + <!--Todo: process Response Object and its headers, schema, examples --> + + <h3 class="field-label">Example data</h3> + <div class="example-data-content-type">Content-Type: application/json</div> + <pre class="example"><code>[ { + "jobID" : { }, + "created" : "2000-01-23T04:56:07.000+00:00", + "name" : "name", + "updated" : "2000-01-23T04:56:07.000+00:00", + "status" : { }, + "info" : "info" +}, { + "jobID" : { }, + "created" : "2000-01-23T04:56:07.000+00:00", + "name" : "name", + "updated" : "2000-01-23T04:56:07.000+00:00", + "status" : { }, + "info" : "info" +} ]</code></pre> + + <h3 class="field-label">Produces</h3> + This API call produces the following media types according to the <span class="header">Accept</span> request header; + the media type will be conveyed by the <span class="header">Content-Type</span> response header. + <ul> + <li><code>application/json</code></li> + </ul> + + <h3 class="field-label">Responses</h3> + <h4 class="field-label">200</h4> + OK + + <h4 class="field-label">206</h4> + Partial Content + + <h4 class="field-label">400</h4> + Bad Request + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">404</h4> + Not Found + <a href="#ErrResponse">ErrResponse</a> + <h4 class="field-label">500</h4> + Internal Server error + <a href="#ErrResponse">ErrResponse</a> + </div> <!-- method --> + <hr/> + + <h2><a name="__Models">Models</a></h2> + [ Jump to <a href="#__Methods">Methods</a> ] + + <h3>Table of Contents</h3> + <ol> + <li><a href="#ArtifactAlias"><code>ArtifactAlias</code> - </a></li> + <li><a href="#ArtifactDescription"><code>ArtifactDescription</code> - </a></li> + <li><a href="#ArtifactFilter"><code>ArtifactFilter</code> - </a></li> + <li><a href="#ArtifactFilterAndSort"><code>ArtifactFilterAndSort</code> - </a></li> + <li><a href="#ArtifactPath"><code>ArtifactPath</code> - </a></li> + <li><a href="#ArtifactSortBy"><code>ArtifactSortBy</code> - </a></li> + <li><a href="#ArtifactSorter"><code>ArtifactSorter</code> - </a></li> + <li><a href="#ArtifactStatus"><code>ArtifactStatus</code> - </a></li> + <li><a href="#ArtifactType"><code>ArtifactType</code> - </a></li> + <li><a href="#ArtifactURI"><code>ArtifactURI</code> - </a></li> + <li><a href="#ErrResponse"><code>ErrResponse</code> - </a></li> + <li><a href="#JobFilter"><code>JobFilter</code> - </a></li> + <li><a href="#JobFilterAndSort"><code>JobFilterAndSort</code> - </a></li> + <li><a href="#JobID"><code>JobID</code> - </a></li> + <li><a href="#JobInfo"><code>JobInfo</code> - </a></li> + <li><a href="#JobSortBy"><code>JobSortBy</code> - </a></li> + <li><a href="#JobSorter"><code>JobSorter</code> - </a></li> + <li><a href="#JobStatus"><code>JobStatus</code> - </a></li> + <li><a href="#SortOrder"><code>SortOrder</code> - </a></li> + <li><a href="#ArtifactInfo"><code>ArtifactInfo</code> - </a></li> + </ol> + + <div class="model"> + <h3><a name="ArtifactAlias"><code>ArtifactAlias</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is an alternative name of an artifact.</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactDescription"><code>ArtifactDescription</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>contains information needed to create new artifact in ArtifactDB.</div> + <div class="field-items"> + <div class="param">JobID (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobID">JobID</a></span> specifies Job for which artifact was created. </div> +<div class="param">Type (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactType">ArtifactType</a></span> </div> +<div class="param">Alias (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactAlias">ArtifactAlias</a></span> </div> +<div class="param">URI (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactURI">ArtifactURI</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactFilter"><code>ArtifactFilter</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is used to filter results from ArtifactDB.</div> + <div class="field-items"> + <div class="param">JobID (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobID">array[JobID]</a></span> </div> +<div class="param">Type (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactType">array[ArtifactType]</a></span> </div> +<div class="param">Status (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactStatus">array[ArtifactStatus]</a></span> </div> +<div class="param">Alias (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactAlias">array[ArtifactAlias]</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactFilterAndSort"><code>ArtifactFilterAndSort</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>Data for filtering and sorting Weles Jobs lists.</div> + <div class="field-items"> + <div class="param">Filter (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactFilter">ArtifactFilter</a></span> </div> +<div class="param">Sorter (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactSorter">ArtifactSorter</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactPath"><code>ArtifactPath</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>describes path to artifact in ArtifactDB filesystem.</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactSortBy"><code>ArtifactSortBy</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>denotes the key for sorting list of all artifacts.</p> +<ul> +<li>ID - sorting by artifact ID.</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactSorter"><code>ArtifactSorter</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>defines the key for sorting as well as direction of sorting. +When ArtifactSorter is empty, artifacts are sorted by ID, Ascending.</div> + <div class="field-items"> + <div class="param">SortBy (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactSortBy">ArtifactSortBy</a></span> </div> +<div class="param">SortOrder (optional)</div><div class="param-desc"><span class="param-type"><a href="#SortOrder">SortOrder</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactStatus"><code>ArtifactStatus</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>describes artifact status and availability.</p> +<ul> +<li> +<p>DOWNLOADING - artifact is currently being downloaded.</p> +</li> +<li> +<p>READY - artifact has been downloaded and is ready to use.</p> +</li> +<li> +<p>FAILED - file is not available for use (e.g. download failed).</p> +</li> +<li> +<p>PENDING - artifact download has not started yet.</p> +</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactType"><code>ArtifactType</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>denotes type and function of an artifact.</p> +<ul> +<li> +<p>IMAGE - image file.</p> +</li> +<li> +<p>RESULT - all outputs, files built during tests, etc.</p> +</li> +<li> +<p>TEST - additional files uploaded by user for conducting test.</p> +</li> +<li> +<p>YAML - yaml file describing Weles Job.</p> +</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactURI"><code>ArtifactURI</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is used to identify artifact's source.</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ErrResponse"><code>ErrResponse</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is a standard error response containing information about the error. It consists of error type and message.</div> + <div class="field-items"> + <div class="param">type (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> </div> +<div class="param">message (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobFilter"><code>JobFilter</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is used to filter Weles Jobs.</div> + <div class="field-items"> + <div class="param">JobID (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobID">array[JobID]</a></span> </div> +<div class="param">Name (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> </div> +<div class="param">CreatedAfter (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> format: date-time</div> +<div class="param">CreatedBefore (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> format: date-time</div> +<div class="param">UpdatedAfter (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> format: date-time</div> +<div class="param">UpdatedBefore (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> format: date-time</div> +<div class="param">Status (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobStatus">array[JobStatus]</a></span> </div> +<div class="param">Info (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobFilterAndSort"><code>JobFilterAndSort</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>Data for filtering and sorting Weles Jobs lists.</div> + <div class="field-items"> + <div class="param">Filter (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobFilter">JobFilter</a></span> </div> +<div class="param">Sorter (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobSorter">JobSorter</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobID"><code>JobID</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>is a unique identifier for Weles Job.</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobInfo"><code>JobInfo</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>contains information about a Job available for public API.</div> + <div class="field-items"> + <div class="param">jobID (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobID">JobID</a></span> is a unique Job identifier </div> +<div class="param">name (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> is the Job name acquired from yaml file during Job creation. </div> +<div class="param">created (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> is the Job creation time in UTC. format: date-time</div> +<div class="param">updated (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span> is the time of latest Jobs' status modification. format: date-time</div> +<div class="param">status (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobStatus">JobStatus</a></span> specifies current state of the Job. </div> +<div class="param">info (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> provides additional information about current state, e.g. cause of failure </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobSortBy"><code>JobSortBy</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>denotes key for sorting Jobs list. Jobs are sorted by ID (Ascending) by default. +You can sort jobs additionaly by</p> +<ul> +<li> +<p>CreatedDate - sorting by date of creation of the weles job.</p> +</li> +<li> +<p>UpdatedDate - sorting by date of update of the weles job.</p> +</li> +<li> +<p>JobStatus - sorting by the Job Status. Descending order will sort in the order JobStatuses are listed in the docs (from NEW at the start to CANCELED at the end). Ascending will reverse this order. +When sorting is applied, and there are many jobs with the same date/status, they will be sorted by JobID (Ascending)</p> +</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobSorter"><code>JobSorter</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>defines the key for sorting as well as direction of sorting.</div> + <div class="field-items"> + <div class="param">SortBy (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobSortBy">JobSortBy</a></span> </div> +<div class="param">SortOrder (optional)</div><div class="param-desc"><span class="param-type"><a href="#SortOrder">SortOrder</a></span> </div> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="JobStatus"><code>JobStatus</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>specifies state of the Job.</p> +<ul> +<li> +<p>NEW - The new Job has been created.</p> +</li> +<li> +<p>PARSING - Provided yaml file is being parsed and interpreted.</p> +</li> +<li> +<p>DOWNLOADING - Images and/or files required for the test are being downloaded.</p> +</li> +<li> +<p>WAITING - Job is waiting for Boruta worker.</p> +</li> +<li> +<p>RUNNING - Job is being executed.</p> +</li> +<li> +<p>COMPLETED - Job is completed. This is terminal state.</p> +</li> +<li> +<p>FAILED - Job execution has failed. This is terminal state.</p> +</li> +<li> +<p>CANCELED -Job has been canceled with API call. This is terminal state.</p> +</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="SortOrder"><code>SortOrder</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'><p>denotes direction of sorting of weles jobs or artifacts.</p> +<ul> +<li> +<p>Ascending - from oldest to newest.</p> +</li> +<li> +<p>Descending - from newest to oldest.</p> +</li> +</ul> +</div> + <div class="field-items"> + </div> <!-- field-items --> + </div> + <div class="model"> + <h3><a name="ArtifactInfo"><code>ArtifactInfo</code> - </a> <a class="up" href="#__Models">Up</a></h3> + <div class='model-description'>describes single artifact stored in ArtifactDB.</div> + <div class="field-items"> + <div class="param">JobID (optional)</div><div class="param-desc"><span class="param-type"><a href="#JobID">JobID</a></span> specifies Job for which artifact was created. </div> +<div class="param">Type (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactType">ArtifactType</a></span> </div> +<div class="param">Alias (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactAlias">ArtifactAlias</a></span> </div> +<div class="param">URI (optional)</div><div class="param-desc"><span class="param-type"><a href="#ArtifactURI">ArtifactURI</a></span> </div> + </div> <!-- field-items --> + </div> + </body> +</html> diff --git a/doc/source/api.txt b/doc/source/api.txt new file mode 100644 index 0000000..c98e7b3 --- /dev/null +++ b/doc/source/api.txt @@ -0,0 +1,7 @@ +### +API +### + + +.. raw:: html + :file: _static/swagger/index.html diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..93cdd62 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,176 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Weles' +copyright = '2018, Samsung Electronics Co., Ltd' +author = 'Samsung Electronics Co., Ltd' + +# The short X.Y version +version = '0.0.1' +# The full version, including alpha/beta/rc tags +release = '0.0.1' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.txt' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Welesdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Weles.tex', 'Weles Documentation', + 'Samsung Electronics Co., Ltd', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'weles', 'Weles Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Weles', 'Weles Documentation', + author, 'Weles', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +def setup(app): + app.add_stylesheet('css/custom.css') # may also be an URL
\ No newline at end of file diff --git a/doc/source/creating-job.txt b/doc/source/creating-job.txt new file mode 100644 index 0000000..09f2f9c --- /dev/null +++ b/doc/source/creating-job.txt @@ -0,0 +1,152 @@ +####################################### +How to create Weles job spec (yamlfile) +####################################### + +************** +Job parameters +************** + +The first section of job specification should be similiar to: + +.. code-block:: yaml + + device_type: qemu + job_name: qemu-pipeline + priority: medium + timeouts: + job: + minutes: 25 # timeout for the whole job + action: + minutes: 5 # default timeout applied for each action; can be overriden in the action itself + + actions: + +``device_type`` is used to test specific device. It depends on device_type +capability in Dryads config. It should define the base device, e.g. Raspberry +Pi 3 would be ``rpi3``. It is planned to add ``caps`` for additional +capabilities. + +``job_name`` will be shown in Alias field of JobInfo. It can be used to filter +specific type of tests from Weles. + +``timeouts`` contains job and action timeouts. ``job`` timeout constrains +execution of whole job on Dryad, ``action`` timeout constrains each action +(unless action has custom timeout). + +``priority`` can be low, medium or high. + +``actions`` are described below. + + +*********** +Job actions +*********** + +``deploy`` section contains information about deployment phase - images to +flash the DUT and partition layout. + +``boot`` section contains information necessary to boot the device - login +information, prompt. + +``test`` section contains list of test cases. + +Deploy +====== + +Sample deploy section: + +.. code-block:: yaml + + - deploy: + timeout: + minutes: 20 + images: # list of images + - uri: https://images.validation.linaro.org/kvm/standard/stretch-1.img.gz + checksum_uri: https://images.validation.linaro.org/kvm/standard/stretch-1.md5 + checksum_type: md5 + compression: gz + - uri: https://images.validation.linaro.org/kvm/standard/stretch-2.img.zip + checksum_uri: https://images.validation.linaro.org/kvm/standard/stretch-2.md5 + checksum_type: md5 + compression: zip + partition_layout: # list of partitions structures + - id: 1 + device_name: device_name1_string + image_name: image_name1_string + size: 12345 + type: fat + - id: 2 + device_name: device_name2_string + image_name: image_name2_string + size: 23456 + type: ext2 + - id: 3 + device_name: device_name3_string + image_name: image_name3_string + size: 34567 + type: ext3 + +``deploy`` has ``timeout`` property - keep in mind, action timeout will +override it. ``images`` contains list of images to be downloaded. Providing +checksum is not required but recommended. ``partition_layout`` maps partitions +to image names from ``images``. + + +Boot +==== + +Sample boot section: + +.. code-block:: yaml + + - boot: + login: root + password: tizen + timeout: + minutes: 20 + +``boot`` section contains information required to access the device - login to +it and get appropriate prompt. + +Test +==== + +Sample test section: + +.. code-block:: yaml + + - test: + name: test_name + timeout: + minutes: 5 + test_cases: + - case_name: case_name1_string + test_actions: + - push: + uri: uri1_string + dest: path1_string + alias: alias1_string + timeout: + minutes: 6 + - run: + name: executed_command_string + timeout: + minutes: 2 + - pull: + src: path2_string + alias: alias2_string + timeout: + minutes: 1 + +``test`` section contains definitions of ``test_cases``. Each test case +consists of ``test_actions``. Weles currently supports ``push``, ``run`` and +``pull`` ``test_actions``. + +Most common approaches are: + +- run a command which creates a file, pull the file with results +- push a script, run it and pull results back + +Or any other approach that fits your testing needs. + +.. _LAVA: https://www.linaro.org/engineering/projects/lava/ diff --git a/doc/source/dependencies.txt b/doc/source/dependencies.txt new file mode 100644 index 0000000..7ea5c15 --- /dev/null +++ b/doc/source/dependencies.txt @@ -0,0 +1,53 @@ +############ +Requirements +############ + + +**** +Host +**** + +Weles requires running Boruta instance on the same host as Weles (this will +change). + +Additionally you need to have SSHFS installed on the host machine. + +**************************** +Workers registered in Boruta +**************************** + +All workers need to have all MuxPi software (refer to MuxPi documentation): + +* stm +* fota + +Weles requires additional symlinks: + +* ``/usr/local/bin/fota`` to ``/usr/bin/fota`` +* ``/usr/local/bin/stm`` to ``/usr/bin/stm`` + +This is to allow changing flashing software in case of using different method. + +Obviously each worker also needs to have Dryad agent to be registered in +Boruta: + +* dryad + +Weles mounts your job's artifacts via sshfs thus you need that installed on +MuxPi: + +* SSHFS + +Boards need to have scripts to communicate with DUT. Following scripts need to +be present on the MuxPi: + +* ``dut_boot.sh`` - Should boot the device. +* ``dut_copyto.sh`` ``src`` ``dst`` - Should copy files from ``src`` (on MuxPi) + to ``dst`` (on DUT) +* ``dut_copyfrom.sh`` ``src`` ``dst`` - Should copy files from ``src`` (on DUT) + to ``dst`` (on MuxPi) +* ``dut_exec.sh`` ``cmd`` - Should execute the ``cmd`` on DUT +* ``dut_login.sh`` ``user`` ``pass`` - Should log in as ``user`` using ``pass`` + password and start shell on DUT. + +All dut_* scripts should be located in ``/usr/local/bin/`` diff --git a/doc/source/index.txt b/doc/source/index.txt new file mode 100644 index 0000000..9c85d2e --- /dev/null +++ b/doc/source/index.txt @@ -0,0 +1,23 @@ +.. Weles documentation master file, created by + sphinx-quickstart on Fri Sep 21 09:20:51 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to the documentation of Weles! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + readme + dependencies + api + creating-job + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/readme.txt b/doc/source/readme.txt new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.txt @@ -0,0 +1 @@ +.. include:: ../../README.rst |