From 1e91f62e5d16d621bf504658097ee7ab625e7cdd Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Wed, 18 Jul 2018 18:48:25 +0200 Subject: Add README Change-Id: I219454ace706cff56ac37ba24565d838002e7627 Signed-off-by: Alexander Mazuruk Signed-off-by: Pawel Wieczorek --- README | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 1 + 2 files changed, 157 insertions(+) create mode 100644 README create mode 120000 README.rst diff --git a/README b/README new file mode 100644 index 0000000..a6ef4c6 --- /dev/null +++ b/README @@ -0,0 +1,156 @@ +##### +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://git.tizen.org/cgit/tools/muxpi +.. _Boruta: https://git.tizen.org/cgit/tools/boruta +.. _SLAV: https://git.tizen.org/cgit/tools/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 + + +********** +Deployment +********** + + +Local +===== + +Prerequisites +------------- +- git +- make +- `go (1.10+)`_ + +.. _`go (1.10+)`: https://golang.org/doc/install + +Getting sources +--------------- + +Repository is currently on tizen.org which does not support ``go get``. +Move to github.com is planned. Currently, some things need to be done manually. + +Create directory for Weles and Boruta: + + $ mkdir -p $GOPATH/src/git.tizen.org/tools + +Go to that directory: + + $ cd $GOPATH/src/git.tizen.org/tools + +Download Weles: + + $ git clone git://git.tizen.org/tools/weles -b master + +And its dependencies: + +Boruta: + + $ git clone git://git.tizen.org/tools/boruta -b master + +Dep which is used to manage Weles dependencies: + + $ go get -u github.com/golang/dep/cmd/dep + +Go to Weles directory: + + $ cd weles + +Download all dependencies: + + $ make vendor + +Adjust swagger.yml to your instance +----------------------------------- + +Modify following parts of swagger.yml:: + + info: + description: >- + Place your description here. + termsOfService: link your ToS + contact: + email: your@e-mail.com + host: host:port + +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/ + + +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 -- cgit v1.2.3 From 5b45f678255b7a4d2613a471a27989df8f252b3f Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Wed, 18 Jul 2018 14:23:14 +0200 Subject: Add CONTRIBUTING Change-Id: I79a957e52e9c28f70bc2d127611613c3222c3b1c Signed-off-by: Alexander Mazuruk --- CONTRIBUTING | 222 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.rst | 1 + 2 files changed, 223 insertions(+) create mode 100644 CONTRIBUTING create mode 120000 CONTRIBUTING.rst diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..ad94d30 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,222 @@ +############ +Contributing +############ + +.. contents:: Table of Contents + +Weles uses `Tizen Gerrit`_ to manage code and reviews. Currently there is no +issue tracker. Move to Github_ is planned due to lack of ``go get`` feature on +Tizen Gerrit. + +.. _`Tizen Gerrit`: https://review.tizen.org/gerrit/#/admin/projects/tools/weles +.. _Github: https://github.com/ + + +***************** +How to contribute +***************** + +Reporting bugs +============== + +Currently only contact via e-mail is possible. Refer to README. + +Suggesting enhancements +======================= + +Currently only contact via e-mail is possible. Refer to README. + +Code contributions +================== + +Currently only contact via e-mail is possible. Refer to README. + + +*********** +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 +============ + +TODO + +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 -- cgit v1.2.3 From 16fc444cc734c2da26aa738a83c1c33ca63ef7ea Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Thu, 23 Aug 2018 18:20:13 +0200 Subject: Add coding style guide to CONTRIBUTING Change-Id: I72909d21cf7b7c6e19ea4b3c50ce6cec2ec03245 Signed-off-by: Alexander Mazuruk --- CONTRIBUTING | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index ad94d30..5dfb4b4 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -31,7 +31,6 @@ Code contributions Currently only contact via e-mail is possible. Refer to README. - *********** Styleguides *********** @@ -95,7 +94,77 @@ Versioning 2.0`_ . Coding style ============ -TODO +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 ----- -- cgit v1.2.3 From b4a6ebc1377c387675136fe29bcfac4c5fa3fa45 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Fri, 21 Sep 2018 13:42:27 +0200 Subject: Adjust README * Add info regarding docker build * Remove tizen.org related stuff in favor of github.com * Add reminder about setting boruta flag * Fix rst error - lack of newline after a list * Unify lists to use * Change-Id: I3fd43674fc8e482fa1e2e8015c070c056bcbe32a Signed-off-by: Alexander Mazuruk --- README | 100 ++++++++++++++++++++++++++++++++--------------------------------- 1 file changed, 49 insertions(+), 51 deletions(-) diff --git a/README b/README index a6ef4c6..23cde2a 100644 --- a/README +++ b/README @@ -12,10 +12,10 @@ 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 +* 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://git.tizen.org/cgit/tools/muxpi @@ -25,16 +25,16 @@ Weles responsibilities include: 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: +* 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 + * 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 @@ -43,72 +43,68 @@ Check sample yaml for Weles in parser/sample_yaml Deployment ********** - -Local -===== +Docker +====== Prerequisites -------------- -- git -- make -- `go (1.10+)`_ -.. _`go (1.10+)`: https://golang.org/doc/install +* Docker_ +* Make_ -Getting sources ---------------- +.. _Docker: https://www.docker.com/ +.. _Make: https://www.gnu.org/software/make/ -Repository is currently on tizen.org which does not support ``go get``. -Move to github.com is planned. Currently, some things need to be done manually. -Create directory for Weles and Boruta: +Clone Weles and go to that directory:: - $ mkdir -p $GOPATH/src/git.tizen.org/tools + $ git clone https://github.com/SamsungSLAV/weles.git && cd weles -Go to that directory: +Adjust swagger.yml to your instance. You should only edit following fields: - $ cd $GOPATH/src/git.tizen.org/tools +* description +* termsOfService +* contact +* host -Download Weles: +And build Weles:: - $ git clone git://git.tizen.org/tools/weles -b master + $ make docker-build + +Local +===== -And its dependencies: +- git +- make +- `go (1.10+)`_ -Boruta: +.. _`go (1.10+)`: https://golang.org/doc/install - $ git clone git://git.tizen.org/tools/boruta -b master -Dep which is used to manage Weles dependencies: +Go get it and go to weles directory:: - $ go get -u github.com/golang/dep/cmd/dep + $ go get github.com/SamsungSLAV/weles + $ cd $GOPATH/src/github.com/SamsungSLAV/weles -Go to Weles directory: +Weles uses Dep to manage dependencies; if you dont have it, go get it:: - $ cd weles + $ go get -u github.com/golang/dep/cmd/dep Download all dependencies: $ make vendor -Adjust swagger.yml to your instance ------------------------------------ +Adjust swagger.yml to your instance. You should only edit following fields: -Modify following parts of swagger.yml:: +* description +* termsOfService +* contact +* host - info: - description: >- - Place your description here. - termsOfService: link your ToS - contact: - email: your@e-mail.com - host: host:port - -Regenerate server code with your changes in the swagger.yml file: +Regenerate server code with your changes in the swagger.yml file:: $ make swagger-server-generate -And finally we can build Weles! +And finally we can build Weles:: $ make server @@ -131,7 +127,9 @@ 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 -- cgit v1.2.3 From f47499be7d412530b82049504ad84dcaffc5760e Mon Sep 17 00:00:00 2001 From: Michal Sidor Date: Fri, 3 Aug 2018 09:00:49 +0200 Subject: Initialize Sphinx documentation Generated using Sphinx v1.8.0: cd doc sphinx-quickstart --quiet --sep --project="Weles" --no-batchfile \ --author="Samsung Electronics Co., Ltd" --suffix .txt \ --language en -v 0.0.1 . sed -i -e '/modindex/d' source/index.txt Headline of index.txt was altered to avoid awkward "Weles's". Change-Id: I215c8b9e70d64165d8c309a117beb438bd0a0f12 Signed-off-by: Michal Sidor --- doc/Makefile | 19 ++++++ doc/source/conf.py | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/index.txt | 19 ++++++ 3 files changed, 211 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.txt 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/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..3a505dd --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,173 @@ +# -*- 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'] \ No newline at end of file diff --git a/doc/source/index.txt b/doc/source/index.txt new file mode 100644 index 0000000..f6a8be9 --- /dev/null +++ b/doc/source/index.txt @@ -0,0 +1,19 @@ +.. 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: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` -- cgit v1.2.3 From 00ff300d66518a4afd6a7b302264a1084fe3956e Mon Sep 17 00:00:00 2001 From: Michal Sidor Date: Thu, 2 Aug 2018 11:11:05 +0200 Subject: Add Sphinx build environment in Docker Docker file same as for MuxPi and Boruta including: - support for Python (required by Sphinx) - Java (required by plantuml plugin) - a few Sphinx plugins such as seqdiag Change-Id: I154b7def3e147faee5090940aaf14459933aacc9 Signed-off-by: Michal Sidor --- doc/Dockerfile | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 doc/Dockerfile 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 " + +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 -- cgit v1.2.3 From 0471408f8269b5a6a339650abeb0e35b9387ee94 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Thu, 20 Sep 2018 18:52:16 +0200 Subject: Adjust Makefile Change-Id: Iee1d410de72f70617751c22218b08aafa9406c28 Signed-off-by: Alexander Mazuruk Signed-off-by: Michal Sidor --- Makefile | 109 ++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 29 deletions(-) diff --git a/Makefile b/Makefile index ad38d27..d0f3dbe 100644 --- a/Makefile +++ b/Makefile @@ -1,25 +1,33 @@ -DEV_TOOLS_DIR = ./bin/dev-tools +BIN_DIR = bin +DEV_TOOLS_DIR = $(BIN_DIR)/dev-tools DEV_TOOLS = ./vendor/github.com/golang/mock/mockgen ./vendor/github.com/go-swagger/go-swagger/cmd/swagger MOCKGEN_BIN = $(DEV_TOOLS_DIR)/mockgen SWAGGER_BIN = $(DEV_TOOLS_DIR)/swagger - DEV_TOOLS_BIN = $(MOCKGEN_BIN) $(SWAGGER_BIN) rwildcard=$(foreach d,$(wildcard $1*),$(call rwildcard,$d/,$2) $(filter $(subst *,%,$2),$d)) - WELES_FILES = $(filter-out *_test.go, $(call rwildcard, , *.go)) SERVER_MAIN = cmd/weles-server/main.go -SERVER_BIN = bin/weles-server - -.PHONY: server -server: vendor $(WELES_FILES) +SERVER_BIN = $(BIN_DIR)/weles-server + +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: weles +weles: vendor $(WELES_FILES) go build -o $(SERVER_BIN) $(SERVER_MAIN) -# dep ensure is run after swagger generation to update Gopkg.lock with packages needed to build server -.PHONY: swagger-server-generate -swagger-server-generate: swagger.yml COPYING +# server recipe generates Weles server code. dep ensure is run after swagger +# generation to update Gopkg.lock with packages needed to build server. +.PHONY: server +server: swagger.yml COPYING ./$(DEV_TOOLS_DIR)/swagger generate server \ -A weles \ -f ./swagger.yml \ @@ -31,19 +39,59 @@ swagger-server-generate: swagger.yml COPYING --compatibility-mode=modern dep ensure +.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: swagger-docs-html -swagger-docs-html: swagger.yml - mkdir -p doc/build/swagger +.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 @@ -55,18 +103,21 @@ Gopkg.lock: Gopkg.toml dep-update: clean-vendor dep ensure -update -# clean-vendor has not been added to vendor dependencies as dep is able to check out appropriate -# packages on versions set in the Gopkg.lock file. Removing vendor would force dep to re-download -# all the packages instead of only the missing ones. Global prune is turned off (see Gopkg.toml -# for explanation) thus vendor recipe will leave unused packages in the vendor/ directory. If that -# bothers you, run sequentially clean-vendor and vendor recipes. +# clean-vendor has not been added to vendor dependencies as dep is able to +# check out appropriate packages on versions set in the Gopkg.lock file. +# Removing vendor would force dep to re-download all the packages instead of +# only the missing ones. Global prune is turned off (see Gopkg.toml for +# explanation) thus vendor recipe will leave unused packages in the vendor/ +# directory. If that bothers you, run sequentially clean-vendor and vendor +# recipes. .PHONY: clean-vendor clean-vendor: - rm -rf vendor + -rm -rf vendor -# Due to lack of standard approach to naming and separation of both interfaces and generated mock files -# below recipe does not have any file dependencies and is PHONY. Interface changes should be rare thus -# it is up to the developer to regenerate mocks after interface changes. +# Due to lack of standard approach to naming and separation of both interfaces +# and generated mock files below recipe does not have any file dependencies and +# is PHONY. Interface changes should be rare thus it is up to the developer to +# regenerate mocks after interface changes. .PHONY: mocks mocks: tools go generate ./mock @@ -76,7 +127,7 @@ mocks: tools .PHONY: tools tools: vendor $(DEV_TOOLS_BIN) -# This recipe will rebuild all tools on vendor directory change. -# Due to short build time it is not treated as issue. +# This recipe will rebuild all tools on vendor directory change. Due to short +# build time it is not treated as issue. $(DEV_TOOLS_DIR)/%: $(DEV_TOOLS) go build -o $@ $(filter %$(@F),$(DEV_TOOLS)) -- cgit v1.2.3 From 8ff3914867564171a7765404c68453f07a85ab42 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Thu, 20 Sep 2018 17:01:11 +0200 Subject: Include README in documentation This patch also adds two missing colons to the README to render all code blocks properly. Change-Id: Icd9a73bfb761037000ecf35c9cb5d372d1ffc88b Signed-off-by: Alexander Mazuruk --- README | 4 ++-- doc/source/index.txt | 1 + doc/source/readme.txt | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 doc/source/readme.txt diff --git a/README b/README index 23cde2a..0cecf30 100644 --- a/README +++ b/README @@ -89,7 +89,7 @@ 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: +Download all dependencies:: $ make vendor @@ -110,7 +110,7 @@ And finally we can build Weles:: The binary of Weles will be available in bin/weles-server -Run it with -h flag: +Run it with -h flag:: $ bin/weles-server -h diff --git a/doc/source/index.txt b/doc/source/index.txt index f6a8be9..d28fc48 100644 --- a/doc/source/index.txt +++ b/doc/source/index.txt @@ -10,6 +10,7 @@ Welcome to the documentation of Weles! :maxdepth: 2 :caption: Contents: + readme Indices and tables 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 -- cgit v1.2.3 From 56f4a0a7b2c4d9d6fcda2bbcb29bf3f6b9d34fe1 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Thu, 20 Sep 2018 15:46:17 +0200 Subject: Add API documentation Generated using: $ make docs-swagger Needs css adjustments to alabaster theme. Change-Id: I90eb6277ef046a1d7e5f716bffa29d9523d50616 Signed-off-by: Alexander Mazuruk --- doc/source/_static/swagger/.swagger-codegen-ignore | 23 + .../_static/swagger/.swagger-codegen/VERSION | 1 + doc/source/_static/swagger/index.html | 746 +++++++++++++++++++++ doc/source/api.txt | 7 + doc/source/index.txt | 1 + 5 files changed, 778 insertions(+) create mode 100644 doc/source/_static/swagger/.swagger-codegen-ignore create mode 100644 doc/source/_static/swagger/.swagger-codegen/VERSION create mode 100644 doc/source/_static/swagger/index.html create mode 100644 doc/source/api.txt 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 @@ + + + + Weles + + + +

Weles

+
This is a Weles server. You can find out more about Weles at http://tbd.tbd.
+
More information: https://helloreverb.com
+
Contact Info: tbd@tbd.com
+
Version: 0.0.0
+
BasePath:/api/v1
+
Apache 2.0
+
http://www.apache.org/licenses/LICENSE-2.0.html
+

Access

+ +

Methods

+ [ Jump to Models ] + +

Table of Contents

+
+

Artifacts

+ +

Jobs

+ + +

Artifacts

+
+
+ Up + 
post /artifacts/list
+
List artifacts with filter and sort features (artifactLister)
+
ArtifactLister returns information on filtered Weles artifacts.
+ + +

Consumes

+ This API call consumes the following media types via the Content-Type request header: +
    +
  • application/json
    • +
+ +

Request body

+
+
artifactFilterAndSort ArtifactFilterAndSort (optional)
+ +
Body Parameter — Artifact Filter and Sort object.
+ +
+ + +

Query parameters

+
+
after (optional)
+ +
Query Parameter — ID of the last element from previous page. format: int64
before (optional)
+ +
Query Parameter — ID of first element from next page. format: int64
limit (optional)
+ +
Query Parameter — Custom page limit. Denotes number of ArtifactInfo structures that will be returned. format: int32
+
+ + +

Return type

+
+ array[ArtifactInfo] + +
+ + + +

Example data

+
Content-Type: application/json
+ 
[ "", "" ]
+ +

Produces

+ This API call produces the following media types according to the Accept request header; + the media type will be conveyed by the Content-Type response header. +
    +
  • application/json
    • +
+ +

Responses

+

200

+ OK + +

206

+ Partial Content + +

400

+ Bad Request + ErrResponse +

404

+ Not Found + ErrResponse +

500

+ Internal Server error + ErrResponse +
+
+

Jobs

+
+
+ Up + 
post /jobs/{JobID}/cancel
+
Cancel existing job (jobCanceler)
+
JobCanceler stops execution of Job identified by JobID.
+ +

Path parameters

+
+
JobID (required)
+ +
Path Parameter — format: uint64
+
+ +

Consumes

+ This API call consumes the following media types via the Content-Type request header: +
    +
  • application/json
    • +
+ + + + + + + + + +

Produces

+ This API call produces the following media types according to the Accept request header; + the media type will be conveyed by the Content-Type response header. +
    +
  • application/json
    • +
+ +

Responses

+

204

+ No Content + +

403

+ Forbidden + ErrResponse +

404

+ Not Found + ErrResponse +

500

+ Internal Server error + ErrResponse +
+
+
+
+ Up + 
post /jobs
+
Add new job (jobCreator)
+
adds new Job in Weles using recipe passed in YAML format.
+ + +

Consumes

+ This API call consumes the following media types via the Content-Type request header: +
    +
  • multipart/form-data
    • +
+ + + + +

Form parameters

+
+
yamlfile (required)
+ +
Form Parameter — is Job description yaml file.
+
+ +

Return type

+
+ JobID + +
+ + + +

Example data

+
Content-Type: application/json
+ 
{ }
+ +

Produces

+ This API call produces the following media types according to the Accept request header; + the media type will be conveyed by the Content-Type response header. +
    +
  • application/json
    • +
+ +

Responses

+

201

+ Created + JobID +

415

+ Unsupported media type + ErrResponse +

422

+ Unprocessable entity + ErrResponse +

500

+ Internal Server error + ErrResponse +
+
+
+
+ Up + 
post /jobs/list
+
List jobs with filter and sort features (jobLister)
+
JobLister returns information on filtered Weles Jobs.
+ + +

Consumes

+ This API call consumes the following media types via the Content-Type request header: +
    +
  • application/json
    • +
+ +

Request body

+
+
jobFilterAndSort JobFilterAndSort (optional)
+ +
Body Parameter — Job Filter and Sort object.
+ +
+ + +

Query parameters

+
+
after (optional)
+ +
Query Parameter — JobID of the last element from previous page. format: uint64
before (optional)
+ +
Query Parameter — JobID of first element from next page. format: uint64
limit (optional)
+ +
Query Parameter — Custom page limit. Denotes number of JobInfo structures that will be returned. format: int32
+
+ + +

Return type

+
+ array[JobInfo] + +
+ + + +

Example data

+
Content-Type: application/json
+ 
[ {
+  "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"
+} ]
+ +

Produces

+ This API call produces the following media types according to the Accept request header; + the media type will be conveyed by the Content-Type response header. +
    +
  • application/json
    • +
+ +

Responses

+

200

+ OK + +

206

+ Partial Content + +

400

+ Bad Request + ErrResponse +

404

+ Not Found + ErrResponse +

500

+ Internal Server error + ErrResponse +
+
+ +

Models

+ [ Jump to Methods ] + +

Table of Contents

+
    +
  1. ArtifactAlias -
    2. +
  2. ArtifactDescription -
    3. +
  3. ArtifactFilter -
    4. +
  4. ArtifactFilterAndSort -
    5. +
  5. ArtifactPath -
    6. +
  6. ArtifactSortBy -
    7. +
  7. ArtifactSorter -
    8. +
  8. ArtifactStatus -
    9. +
  9. ArtifactType -
    10. +
  10. ArtifactURI -
    11. +
  11. ErrResponse -
    12. +
  12. JobFilter -
    13. +
  13. JobFilterAndSort -
    14. +
  14. JobID -
    15. +
  15. JobInfo -
    16. +
  16. JobSortBy -
    17. +
  17. JobSorter -
    18. +
  18. JobStatus -
    19. +
  19. SortOrder -
    20. +
  20. ArtifactInfo -
    21. +
+ +
+

ArtifactAlias - Up

+
is an alternative name of an artifact.
+
+
+
+
+

ArtifactDescription - Up

+
contains information needed to create new artifact in ArtifactDB.
+
+
JobID (optional)
JobID specifies Job for which artifact was created.
+
Type (optional)
ArtifactType
+
Alias (optional)
ArtifactAlias
+
URI (optional)
ArtifactURI
+
+
+
+

ArtifactFilter - Up

+
is used to filter results from ArtifactDB.
+
+
JobID (optional)
array[JobID]
+
Type (optional)
array[ArtifactType]
+
Status (optional)
array[ArtifactStatus]
+
Alias (optional)
array[ArtifactAlias]
+
+
+
+

ArtifactFilterAndSort - Up

+
Data for filtering and sorting Weles Jobs lists.
+
+
Filter (optional)
ArtifactFilter
+
Sorter (optional)
ArtifactSorter
+
+
+
+

ArtifactPath - Up

+
describes path to artifact in ArtifactDB filesystem.
+
+
+
+
+

ArtifactSortBy - Up

+

denotes the key for sorting list of all artifacts.

+
    +
  • ID - sorting by artifact ID.
    • +
+
+
+
+
+
+

ArtifactSorter - Up

+
defines the key for sorting as well as direction of sorting. +When ArtifactSorter is empty, artifacts are sorted by ID, Ascending.
+
+
SortBy (optional)
ArtifactSortBy
+
SortOrder (optional)
SortOrder
+
+
+
+

ArtifactStatus - Up

+

describes artifact status and availability.

+
    +
  • +

    DOWNLOADING - artifact is currently being downloaded.

    +
    • +
  • +

    READY - artifact has been downloaded and is ready to use.

    +
    • +
  • +

    FAILED - file is not available for use (e.g. download failed).

    +
    • +
  • +

    PENDING - artifact download has not started yet.

    +
    • +
+
+
+
+
+
+

ArtifactType - Up

+

denotes type and function of an artifact.

+
    +
  • +

    IMAGE - image file.

    +
    • +
  • +

    RESULT - all outputs, files built during tests, etc.

    +
    • +
  • +

    TEST - additional files uploaded by user for conducting test.

    +
    • +
  • +

    YAML - yaml file describing Weles Job.

    +
    • +
+
+
+
+
+
+

ArtifactURI - Up

+
is used to identify artifact's source.
+
+
+
+
+

ErrResponse - Up

+
is a standard error response containing information about the error. It consists of error type and message.
+
+
type (optional)
String
+
message (optional)
String
+
+
+
+

JobFilter - Up

+
is used to filter Weles Jobs.
+
+
JobID (optional)
array[JobID]
+
Name (optional)
array[String]
+
CreatedAfter (optional)
Date format: date-time
+
CreatedBefore (optional)
Date format: date-time
+
UpdatedAfter (optional)
Date format: date-time
+
UpdatedBefore (optional)
Date format: date-time
+
Status (optional)
array[JobStatus]
+
Info (optional)
array[String]
+
+
+
+

JobFilterAndSort - Up

+
Data for filtering and sorting Weles Jobs lists.
+
+
Filter (optional)
JobFilter
+
Sorter (optional)
JobSorter
+
+
+
+

JobID - Up

+
is a unique identifier for Weles Job.
+
+
+
+
+

JobInfo - Up

+
contains information about a Job available for public API.
+
+
jobID (optional)
JobID is a unique Job identifier
+
name (optional)
String is the Job name acquired from yaml file during Job creation.
+
created (optional)
Date is the Job creation time in UTC. format: date-time
+
updated (optional)
Date is the time of latest Jobs' status modification. format: date-time
+
status (optional)
JobStatus specifies current state of the Job.
+
info (optional)
String provides additional information about current state, e.g. cause of failure
+
+
+
+

JobSortBy - Up

+

denotes key for sorting Jobs list. Jobs are sorted by ID (Ascending) by default. +You can sort jobs additionaly by

+
    +
  • +

    CreatedDate - sorting by date of creation of the weles job.

    +
    • +
  • +

    UpdatedDate - sorting by date of update of the weles job.

    +
    • +
  • +

    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)

    +
    • +
+
+
+
+
+
+

JobSorter - Up

+
defines the key for sorting as well as direction of sorting.
+
+
SortBy (optional)
JobSortBy
+
SortOrder (optional)
SortOrder
+
+
+
+

JobStatus - Up

+

specifies state of the Job.

+
    +
  • +

    NEW - The new Job has been created.

    +
    • +
  • +

    PARSING - Provided yaml file is being parsed and interpreted.

    +
    • +
  • +

    DOWNLOADING - Images and/or files required for the test are being downloaded.

    +
    • +
  • +

    WAITING - Job is waiting for Boruta worker.

    +
    • +
  • +

    RUNNING - Job is being executed.

    +
    • +
  • +

    COMPLETED - Job is completed. This is terminal state.

    +
    • +
  • +

    FAILED - Job execution has failed. This is terminal state.

    +
    • +
  • +

    CANCELED -Job has been canceled with API call. This is terminal state.

    +
    • +
+
+
+
+
+
+

SortOrder - Up

+

denotes direction of sorting of weles jobs or artifacts.

+
    +
  • +

    Ascending - from oldest to newest.

    +
    • +
  • +

    Descending - from newest to oldest.

    +
    • +
+
+
+
+
+
+

ArtifactInfo - Up

+
describes single artifact stored in ArtifactDB.
+
+
JobID (optional)
JobID specifies Job for which artifact was created.
+
Type (optional)
ArtifactType
+
Alias (optional)
ArtifactAlias
+
URI (optional)
ArtifactURI
+
+
+ + 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/index.txt b/doc/source/index.txt index d28fc48..6935472 100644 --- a/doc/source/index.txt +++ b/doc/source/index.txt @@ -11,6 +11,7 @@ Welcome to the documentation of Weles! :caption: Contents: readme + api Indices and tables -- cgit v1.2.3 From 108093e27c0ec46edc3c49b3ee8fca3f3ff25e8e Mon Sep 17 00:00:00 2001 From: Katarzyna Gorska Date: Fri, 12 Oct 2018 16:37:18 +0200 Subject: Adjust CSS for generated API documentation Hotfix due to conflict between alabaster theme and generated html document from swagger. Changing theme across repositories requires more work thus css fix is applied. Verification: $ make docs $ xdg-open doc/build/html/api.html $ sensible-browser doc/build/html/api.html Should not have any unreadable text. Change-Id: I2c588e376a55b5da163cfe31bfacb752cd83dcfd Signed-off-by: Katarzyna Gorska --- doc/source/_static/css/custom.css | 16 ++++++++++++++++ doc/source/conf.py | 5 ++++- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 doc/source/_static/css/custom.css 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/conf.py b/doc/source/conf.py index 3a505dd..93cdd62 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -170,4 +170,7 @@ epub_title = project # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] \ No newline at end of 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 -- cgit v1.2.3 From 7cb04017fd147847ecf2f1e265948321c7dcdc2c Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Mon, 24 Sep 2018 08:26:25 +0200 Subject: Document creating a job Quickly written guide on how to create Weles job yaml. Change-Id: Id7b2949dfb7d332d37f557068646bb338e12c892 Signed-off-by: Alexander Mazuruk --- doc/source/creating-job.txt | 152 ++++++++++++++++++++++++++++++++++++++++++++ doc/source/index.txt | 1 + 2 files changed, 153 insertions(+) create mode 100644 doc/source/creating-job.txt 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/index.txt b/doc/source/index.txt index 6935472..14bac5d 100644 --- a/doc/source/index.txt +++ b/doc/source/index.txt @@ -12,6 +12,7 @@ Welcome to the documentation of Weles! readme api + creating-job Indices and tables -- cgit v1.2.3 From 471a04ed693807c586f9059a47fa7d452d356a3a Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Mon, 24 Sep 2018 08:44:03 +0200 Subject: Add Weles requirements/dependencies to docs Change-Id: Id520f1fa9c6757cf22bb04e31bb5f1ce07076375 Signed-off-by: Alexander Mazuruk --- doc/source/dependencies.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++ doc/source/index.txt | 1 + 2 files changed, 54 insertions(+) create mode 100644 doc/source/dependencies.txt 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 index 14bac5d..9c85d2e 100644 --- a/doc/source/index.txt +++ b/doc/source/index.txt @@ -11,6 +11,7 @@ Welcome to the documentation of Weles! :caption: Contents: readme + dependencies api creating-job -- cgit v1.2.3 From aef728e2bf61e09fe9d795035be15e2c9fc8a225 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Wed, 19 Dec 2018 18:12:50 +0100 Subject: Adjustments after github transition Change-Id: Ic78791c89965b36111cc48ef1e94fabc37eaa3a9 Signed-off-by: Alexander Mazuruk --- CONTRIBUTING | 14 ++++++-------- README | 6 +++--- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index 5dfb4b4..5283d76 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -4,12 +4,10 @@ Contributing .. contents:: Table of Contents -Weles uses `Tizen Gerrit`_ to manage code and reviews. Currently there is no -issue tracker. Move to Github_ is planned due to lack of ``go get`` feature on -Tizen Gerrit. +We use `Github`_ for managing code and issues and `GerritHub`_ for reviews. -.. _`Tizen Gerrit`: https://review.tizen.org/gerrit/#/admin/projects/tools/weles -.. _Github: https://github.com/ +.. _GerritHub: https://review.gerrithub.io/admin/projects/SamsungSLAV/weles +.. _Github: https://github.com/SamsungSLAV/weles ***************** @@ -19,17 +17,17 @@ How to contribute Reporting bugs ============== -Currently only contact via e-mail is possible. Refer to README. +Create issue on `GitHub`_. Suggesting enhancements ======================= -Currently only contact via e-mail is possible. Refer to README. +Create issue on `GitHub`_. Code contributions ================== -Currently only contact via e-mail is possible. Refer to README. +Check issues on `Github`_. *********** Styleguides diff --git a/README b/README index 0cecf30..f3d8880 100644 --- a/README +++ b/README @@ -18,9 +18,9 @@ Weles responsibilities include: * presenting results in a human and computer-readable form .. [#] Device Under Test -.. _MuxPi: https://git.tizen.org/cgit/tools/muxpi -.. _Boruta: https://git.tizen.org/cgit/tools/boruta -.. _SLAV: https://git.tizen.org/cgit/tools/slav +.. _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: -- cgit v1.2.3 From d8adb7ecee1e12051464159f3c9e36b0c2cb5ea6 Mon Sep 17 00:00:00 2001 From: Alexander Mazuruk Date: Wed, 19 Dec 2018 18:16:52 +0100 Subject: Add link to documentation to README Change-Id: Ifda97af1f758b6ffd5f8e94920d876982e5e1f68 Signed-off-by: Alexander Mazuruk --- README | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README b/README index f3d8880..bfa2883 100644 --- a/README +++ b/README @@ -39,6 +39,15 @@ User provides a yaml file containing all neccessary information to perform tests 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 ********** -- cgit v1.2.3