Add workflows + howto contribute to marketplace (#16)

* add workflows with howtos
* add howto-marketplace
* address changes

source/user/howto/add-to-DEEP-marketplace.rst

@@ -0,0 +1,62 @@
+Add you model/service to the DEEP marketplace
+=============================================
+
+This document describes how to add your trained service or model to the DEEP marketplace.
+
+Creating the Github repositories
+--------------------------------
+
+You model must have a repository to host the code and a repository to host the Dockerfiles. Both these repositories can he hosted under your personal Github account. Naming conventions are that the Docker repo name is the same as the code repo name with the prefix ``DEEP-OC-``.
+
+A typical example of this can be:
+
+* `deephdc/image-classification-tf <https://github.com/deephdc/image-classification-tf>`_ - The Github repo hosting the code of an image classfication model.
+* `deephdc/DEEP-OC-image-classification-tf <https://github.com/deephdc/DEEP-OC-image-classification-tf>`_ - The Github repo hosting the Dockerfiles of the image classification model.
+
+In case you are only developing a service based on an already existing model (like for example developing an animal classifier based on the image-classification-tf module) you only need to create the Docker repo.
+
+The code repo
+^^^^^^^^^^^^^
+
+This is the repo containing the code of your model. If you are adding a service (ie. a trained model) the weights of the trained model must be stored in a location accessible over a network connection, so that your container can download them upon creation. A few MUSTs your code has to comply with in order to ensure compatibility and ease of use:
+
+* your code must be packaged in order to be ``pip`` installable. This should be the default behaviour if you used the :doc:`DEEP cookiecutter template <../overview/cookiecutter-template>` to develop your code.
+* your code must be integrated with the DEEPaaS API. Check :ref:`this guide <user/overview/api:Integrate your model with the API>` on how to do this.
+
+The Docker repo
+^^^^^^^^^^^^^^^
+
+This repo contains has to contain at least the following files:
+
+* ``Dockerfile``
+
+   This is the file to build a container from your application. If you developed your application from the :doc:`DEEP cookiecutter template <../overview/cookiecutter-template>` you should have a draft of this file under the ``./docker`` folder (although you might need to add additional code depending on the requirements of your model).
+
+   If you are adding a service instead of a model, it is good practice to draw inspiration from the Dockerfiles of other services derived from the same model (for example the `plant classification Dockerfile <https://github.com/deephdc/DEEP-OC-plants-classification-tf/blob/master/Dockerfile>`_ derived from the `image classification model <https://github.com/deephdc/DEEP-OC-image-classification-tf>`_).
+
+   Some steps common to all Dockerfiles include cloning the model code repo, pip installing the DEEPaaS API, installing rclone and downloading the trained weights if you are adding a service. For the details of all these steps please refer to this `Dockerfile example <https://github.com/deephdc/DEEP-OC-plants-classification-tf/blob/master/Dockerfile>`_.
+
+* ``Jenkinsfile``
+
+   This is the file that runs the Jenkins pipeline. You can copy this `Jenkinsfile example <https://github.com/deephdc/DEEP-OC-plants-classification-tf/blob/master/Jenkinsfile>`_ replacing the repo names with your own Docker repo name.
+
+* ``metadata.json``
+
+   This file contains the information that is going to be displayed in the Marketplace. You can build your own starting from this `metadata.json example <https://github.com/deephdc/DEEP-OC-plants-classification-tf/blob/master/metadata.json>`_
+
+Making the Pull Request
+-----------------------
+
+Once your repos are set it's time to make a PR to add your model to the marketplace!
+For this you have to fork the code of the DEEP marketplace (`deephdc/deephdc.github.io <https://github.com/deephdc/deephdc.github.io>`_) and add your Docker repo name at the end of the ``project_apps.yml`` file in the **pelican** branch.
+
+.. code-block:: console
+
+    git clone -b pelican https://github.com/[my-github-fork]
+    cd [my-github-fork]
+    echo '- module: https://github.com/[my-account-name]/DEEP-OC-[my-app-name]' >> project_apps.yml
+    git commit -a -m "adding new module to the catalogue"
+    git push
+
+Once the changes are done, make a PR of your fork to the original repo (again to the pelican branch) and wait for approval.
+Check the `GitHub Standard Fork & Pull Request Workflow <https://gist.github.com/Chaser324/ce0505fbed06b947d962>`_ in case of doubt.

source/user/howto/index.rst

@@ -10,6 +10,7 @@ HowTo's
    Train a model locally <train-model-locally>
    Train a model remotely <train-model-remotely>
    Test a service locally <try-service-locally>
+   Add model/service to the DEEP marketplace <add-to-DEEP-marketplace>
    Use rclone <rclone>
    Install and configure oidc-agent <oidc-agent>
    Video demos <video-demos>

source/user/overview/index.rst

@@ -5,7 +5,7 @@ Overview
    :maxdepth: 1
    :glob:
 
-   architecture
-   user-roles
-   cookiecutter-template
-   api
+   DEEP architecture <architecture>
+   User roles and workflows <user-roles>
+   DEEP Cookiecutter template <cookiecutter-template>
+   DEEPaaS API <api>

source/user/overview/user-roles.rst

@@ -22,6 +22,10 @@ that has been containerized, and use it to classify their own plant images.
 * solutions to run the inference in the Cloud or in your local resources
 * the ability to develop complex topologies by composing different modules
 
+**Related HowTo's:**
+
+* :doc:`How to try a service locally <../howto/try-service-locally>`
+
 
 The intermediate user
 ---------------------
@@ -44,6 +48,12 @@ model and retrain it to perform `seed classification <https://marketplace.deep-h
 * the ability to deploy the developed service on Cloud resources
 * the ability to share the service with other users in the user's catalogue
 
+**Related HowTo's:**
+
+* :doc:`How to train a model locally <../howto/train-model-locally>`
+* :doc:`How to train a model remotely <../howto/train-model-remotely>`
+* :doc:`How to add your service to the DEEP Marketplace <../howto/add-to-DEEP-marketplace>`
+
 
 The advanced user
 -----------------
@@ -64,3 +74,11 @@ models.
 * the ability to share the module with other users in the user's :ref:`catalogue <user/overview/architecture:The marketplace>`
 * the possibility to :ref:`integrate your module <user/overview/api:Integrate your model with the API>` with
   the :ref:`API <user/overview/architecture:The API>` to enable easier user interaction
+
+
+**Related HowTo's:**
+
+* :doc:`How to use the DEEP Cookiecutter template for model development <cookiecutter-template>`
+* :doc:`How to develop your own machine learning model <../howto/develop-model>`
+* :ref:`How to integrate your model with the DEEPaaS API <user/overview/api:Integrate your model with the API>`
+* :doc:`How to add your model to the DEEP Marketplace <../howto/add-to-DEEP-marketplace>`