Merge pull request #41 from interaction-lab/feature/testing-framework

Feature/testing framework

.gitignore

@@ -118,3 +118,5 @@ dockerfiles/config/private-keys.json
 harmoni_core/harmoni_decision/launch/hardware_service.launch
 harmoni_core/harmoni_decision/launch/harmoni_service.launch
 harmoni_dialogues/harmoni_bot/config/configuration.yaml
+
+doc/_build

doc/Contributions.rst

@@ -0,0 +1,10 @@
+Contributions
+*************
+Contributions are welcome! Especially starting here with an explanation of how to contribute!
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   tutorials/Contributing-Package

doc/Overview.rst

@@ -0,0 +1,13 @@
+Overview
+================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   tutorials/Introduction
+   tutorials/Architecture
+   tutorials/Harmoni-and-Docker
+   tutorials/Package-Organization
+   tutorials/Package-List

doc/README.md

@@ -0,0 +1,15 @@
+# Docs instructions
+
+
+Rebuild the docks with: 
+```bash
+cd doc
+pip install -r requirements.txt
+make clean
+sphinx-build -b html . _build
+```
+
+Todo: 
+[ ] Publishing the docs
+[X] Fix broken images
+[ ] Link across pages

doc/Sample-Tutorials.rst

@@ -0,0 +1,19 @@
+Tutorials
+================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   tutorials/Docker-Quickstart
+   tutorials/Multi-Container
+   tutorials/Setup
+   tutorials/Launching-Services
+   tutorials/Running-Packages
+   tutorials/Cordial
+   tutorials/Compose-an-Interaction
+   tutorials/Setting-Up-a-New-Robot
+   tutorials/Configuration
+   tutorials/Cloud-Services
+   tutorials/Usage

doc/Testing.rst

@@ -0,0 +1,9 @@
+Testing
+================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   tutorials/Testing

doc/_autoapi_templates/index.rst

@@ -0,0 +1,15 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

doc/api-link.rst

@@ -0,0 +1,18 @@
+
+
+API
+==========================================
+
+.. image:: ../logo.svg
+  :width: 1000
+  :alt: Alternative text
+
+The API docs are still being fine tuned
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   autoapi/index

harmoni_dialogues/harmoni_bot/doc/conf.py → doc/conf.py

@@ -10,52 +10,67 @@
 # 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('.'))
-
-# to add automatic version setting from your package.xml
 import os
-import catkin_pkg.package
-catkin_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) 
-catkin_package = catkin_pkg.package.parse_package(os.path.join(catkin_dir, catkin_pkg.package.PACKAGE_MANIFEST_FILENAME))
+import sys
+
+# import catkin_pkg.package
+
+# catkin_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# catkin_package = catkin_pkg.package.parse_package(
+#     os.path.join(catkin_dir, catkin_pkg.package.PACKAGE_MANIFEST_FILENAME)
+# )
+sys.path.insert(0, os.path.abspath("../"))
 
-# -- Project information -----------------------------------------------------
 
-project = 'harmoni_bot'
-copyright = '2021, Chris, Micol, Michael'
-author = 'Chris, Micol, Michael'
+# -- Project information -----------------------------------------------------
 
-# The full version, including alpha/beta/rc tags
-version = catkin_package.version
-release = catkin_package.version
-#release = '1.0.0'
+project = "HARMONI"
+copyright = "2021, Chris, Micol, Michael"
+author = "Chris, Micol, Michael"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']
-
+source_suffix = [".rst", ".md"]
+master_doc = "index"
+extensions = [
+    "sphinx.ext.autodoc",  # Core library for html generation from docstrings
+    "sphinx.ext.autosummary",  # Create neat summary tables
+    "myst_parser",
+    "sphinx.ext.napoleon",
+    "autoapi.extension",
+]
+autoapi_type = "python"
+autoapi_dirs = [
+    "../harmoni_actuators",
+    "../harmoni_core",
+    "../harmoni_detectors",
+    "../harmoni_dialogues",
+    "../harmoni_sensors",
+]
+autoapi_add_toctree_entry = True
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+# autoapi_root = "api-link"
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
+templates_path = ["_templates"]
+autoapi_template_dir = "_autoapi_templates"
 # 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 = ['_build', 'Thumbs.db', '.DS_Store']
-
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+autoapi_ignore = ["*test*"]
 
 # -- 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 = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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']
+# html_static_path = ["_static"]

doc/index.rst

@@ -0,0 +1,27 @@
+.. HARMONI documentation master file, created by
+   sphinx-quickstart on Wed May  5 13:13:59 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Human And Robot Modular OpeN Interactions
+==========================================
+
+.. image:: ../logo.svg
+  :width: 1000
+  :alt: Alternative text
+
+Welcome to HARMONI! 
+
+HARMONI is a ROS based tool for creating and controlling human-robot interaction. HARMONI is an open source (MIT License) tool meant to speed up development, collaboration, and experimentation for the HRI community.
+
+Below you will find an overview of the HARMONI platform, walkthroughs and tutorials, guides for testing and contributing, as well as the complete API.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+   :glob:
+
+   Overview
+   Sample-Tutorials
+   Testing
+   Contributions

doc/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx-autoapi
+myst-parser
+sphinx_rtd_theme

doc/tutorials/Architecture.md

@@ -0,0 +1,25 @@
+# Architecture
+
+## HARMONI Repository
+The HARMONI repository is organized into the following packages, based on the fundamental capabilities needed for human-robot interaction:
+  - harmoni_actuators - _controlling hardware (e.g. motors, screens, speakers)_
+  - harmoni_core
+    - harmoni_common_lib - _defines the Harmoni unit and helper functions_
+    - harmoni_common_msgs - _defines harmoni messages and actions_
+    - harmoni_decision - _highest level controller, can play patterns or individual units_
+    - harmoni_pattern - _middle level decision player, defines sequences or patterns for dialog_
+    - harmoni_recorder - _records interactions (WIP)_
+  - harmoni_detectors - _extracting useful information from sensor signals (e.g. transcriptions, facial locations, etc.)_
+  - harmoni_dialogues - _processing user speech (text) and return robot speech (text)_
+  - harmoni_sensors - _reading physical sensors and publishing sensor streams_
+
+![packges](images/PackageOrganization.png)
+
+
+## HARMONI Unit
+
+![unit](images/HarmoniUnitUML.png)
+
+Nearly everything in HARMONI is a ROS node called a HARMONI unit. The HARMONI unit consists of two classes, a Service Server and a Service Manager, which standardize the interface for a given node as shown above.
+
+The Harmoni Unit standardizes the communication and control interface for each node, allowing other nodes to control a unit with minimal knowledge of the internal workings. 

doc/tutorials/Cloud-Services.md

@@ -0,0 +1,53 @@
+# Connecting to Cloud Services
+
+## Setup Amazon Accounts
+(If you are planning to use Lex or Polly) Set up AWS account following these steps: 
+
+Create an Amazon Web Services account. AWS has a 1 year free trial that includes a limited number of Polly usages.
+Keep this in mind so you do not get charged money at the end of the year.
+
+Once you've created an account, create an IAM user to access Polly and/or Lex.
+
+    * Give the IAM user access permissions to AWS Polly and/or Lex.
+    * Give the IAM user access keys. Be sure to save the secret key as you only have one chance to look at it.
+
+https://docs.aws.amazon.com/cli/latest/userguide/install-linux.html - Use this link to install the AWS CLI on your PC.
+
+Then, in the terminal,
+```bash
+$ sudo apt-get install awscli
+$ aws --version
+$ aws configure
+# Enter the IAM user access and secret keys here.
+```
+
+## Setup Google Accounts
+If you are planning on using dialogflow or other google services:
+
+You need to update private-keys.json in ./dockerfiles/config/ with your google credentials.
+When you activate google account API, you can create credentials for connecting HARMONI with your account, following this instraction.
+Get the API key (https://developers.google.com/maps/documentation/maps-static/get-api-key)
+You must have at least one API key associated with your project.
+
+To get an API key:
+
+* Go to the Google Cloud Platform Console.
+* Click the project drop-down and select or create the project for which you want to add an API key.
+* Click the menu button and select APIs & Services > Credentials.
+* On the Credentials page, click + Create Credentials > Create ID client OAuth.
+* Click Service Account, fill the input text with your name. Set the role to Editor, and click end.
+* Click the menu button and select APIs & Services > Credentials. In the Service Account table (at the bottom of the page) the account you just created will be displayed. Click on edit. Click on add new keys, and save it.
+* Click Close.
+* The new API key is listed on the Credentials page under API Keys.
+(Remember to restrict the API key before using it in production.)
+* Save private-keys.json
+
+Set credentials on HARMONI:
+
+```bash
+$ cd ~/catkin_ws/src/HARMONI/dockerfiles/config/
+$ nano private-keys.json
+# Copy and paste the json content generated in the previous steps.
+```
+
+Note: Secret keys and configurations are done locally and mounted to images through the Docker-Compose.yml files