Initial documentation

.gitignore

@@ -0,0 +1,3 @@
+.vscode
+_build
+_ext/__pycache__

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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)

README.md

@@ -0,0 +1,20 @@
+<img src="https://dev.ishareworks.org/_static/logo.svg" alt="iSHARE">
+
+# iSHARE Documentation
+The documentation is built with [Sphinx](https://github.com/sphinx-doc/sphinx) using a [rtd theme](https://github.com/readthedocs/sphinx_rtd_theme). The documentation is open sourced to allow the readers to directly contribute on its improvements.
+
+# HTML Generation
+First, make sure you have [Sphinx](http://sphinx-doc.org/) installed. To view the generated HTML before creating a pull request run the following command in the folder where make.bat is located:
+
+```
+C:\Documentation> .\make.bat html
+```
+
+In case not all HTML updated, this could be solved by the following command:
+
+```
+C:\Documentation> .\make.bat clean
+```
+
+# Contribution
+If you find anything that could be improved, feel free to create a pull request to the master branch.

_ext/edit_on_github.py

@@ -0,0 +1,45 @@
+"""
+Sphinx extension to add ReadTheDocs-style "Edit on GitHub" links to the
+sidebar.
+Loosely based on https://github.com/astropy/astropy/pull/347
+"""
+
+import os
+import warnings
+
+
+__licence__ = 'BSD (3 clause)'
+
+
+def get_github_url(app, view, path):
+    return 'https://github.com/{project}/{view}/{branch}/{path}'.format(
+        project=app.config.edit_on_github_project,
+        view=view,
+        branch=app.config.edit_on_github_branch,
+        path=path)
+
+
+def html_page_context(app, pagename, templatename, context, doctree):
+    if templatename != 'page.html':
+        return
+
+    if not app.config.edit_on_github_project:
+        warnings.warn("edit_on_github_project not specified")
+        return
+
+    path = os.path.relpath(doctree.get('source'), app.builder.srcdir)
+    show_url = get_github_url(app, 'blob', path)
+    edit_url = get_github_url(app, 'edit', path)
+
+    context['show_on_github_url'] = show_url
+    context['edit_on_github_url'] = edit_url
+
+    context['display_github'] = True
+    context['github_user'] = app.config.edit_on_github_project.split('/')[0]
+    context['github_version'] = app.config.edit_on_github_branch + '/'
+    context['github_repo'] = app.config.edit_on_github_project.split('/')[1]
+
+def setup(app):
+    app.add_config_value('edit_on_github_project', '', True)
+    app.add_config_value('edit_on_github_branch', 'master', True)
+    app.connect('html-page-context', html_page_context)

_static/ishare.css

@@ -0,0 +1,15 @@
+.wy-side-nav-search {
+    background-color: #EFEFEF;
+}
+
+/* since we use definition lists only for source code,
+   it's more beautiful to have them without rst theme format */
+.rst-content dl dt {
+    display: block !important;
+    margin: 0 !important;
+    font-size: 16px !important;
+    background: #fcfcfc !important; 
+    border: 0 !important;
+    padding: 0 0 6px 0 !important;
+    color: #000000 !important;
+}

_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/ishare.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

_templates/sourcelink.html

@@ -0,0 +1,15 @@
+{%- if show_source and has_source and sourcename %}
+  <h3>{{ _('This Page') }}</h3>
+  <ul class="this-page-menu">
+    <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+           rel="nofollow">{{ _('Show Source') }}</a></li>
+  {%- if show_on_github_url %}
+    <li><a href="{{ show_on_github_url }}"
+           rel="nofollow">{{ _('Show on GitHub') }}</a></li>
+  {%- endif %}
+  {%- if edit_on_github_url %}
+    <li><a href="{{ edit_on_github_url }}"
+           rel="nofollow">{{ _('Edit on GitHub') }}</a></li>
+  {%- endif %}
+  </ul>
+{%- endif %}

azure-pipelines.yml

@@ -0,0 +1,50 @@
+trigger:
+  branches:
+    include: 
+      - master
+  paths:
+    exclude:
+      - README.md
+
+pool:
+  vmImage: 'ubuntu-latest'
+strategy:
+  matrix:
+    Python36:
+      python.version: '3.6'
+      architecture: 'x64'
+
+steps:
+- task: UsePythonVersion@0
+  inputs:
+    versionSpec: '$(python.version)'
+  displayName: 'Use python $(python.version)'
+
+- script: |
+    pip install --upgrade sphinx
+  displayName: 'Install sphinx'
+
+- script: |
+    pip install --upgrade sphinx_rtd_theme
+  displayName: 'Install sphinx_rtd_theme'
+
+- task: CmdLine@2
+  inputs:
+    script: 'make html' 
+    workingDirectory: '$(build.sourcesdirectory)' 
+  displayName: 'Compile documentation'
+
+- task: ArchiveFiles@2
+  inputs:
+    rootFolderOrFile: '$(build.sourcesDirectory)/_build/html'
+    includeRootFolder: false
+    archiveType: 'zip'
+    archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
+    replaceExistingArchive: true
+
+- task: PublishBuildArtifacts@1
+  inputs:
+    PathtoPublish: '$(build.artifactstagingdirectory)'
+    ArtifactName: 'drop'
+    publishLocation: 'Container'
+  displayName: 'Publish documentation as artifact'

common/token.rst

@@ -0,0 +1,110 @@
+.. _refM2MToken:
+
+Access Token (M2M)
+==================
+
+This endpoint is used to obtain an OAuth access token from the party. The format of ``access_token`` is not defined by this specification. They are left to the server and should be opaque to the Service Consumer.
+
+Request
+-------
+
+HTTP methods
+~~~~~~~~~~~~
+
+* POST
+
+Headers
+~~~~~~~
+
+``Content-Type``
+    | **String**.
+    | Defines request body content type. MUST be equal to *application/x-www-form-urlencoded*.
+
+Parameters
+~~~~~~~~~~
+
+``grant_type``
+    | **String**.
+    | OAuth 2.0 grant type. MUST be equal to *client_credentials*.
+
+``scope``
+    | **String**. *Optional*.
+    | OAuth 2.0 scope. Defaults to *iSHARE* if not provided, indicating all rights of the Service Consumer are requested. Other values allow the Service Consumer to get tokens that do not include all rights the Service Consumer has.
+
+``client_id``
+    | **String**.
+    | OpenID Connect 1.0 client ID. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain a valid iSHARE identifier of the Service Consumer.
+
+``client_assertion_type``
+    | **String**.
+    | OpenID Connect 1.0 client assertion type. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST be equal to *urn:ietf:params:oauth:client-assertion-type:jwt-bearer*.
+
+``client_assertion``
+    | **String (JWT)**.
+    | OpenID Connect 1.0 client assertion. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain :ref:`JWT token conform iSHARE specifications<refJWT>`, signed by the client.
+
+Example
+~~~~~~~
+
+::
+
+    > Content-Type: application/x-www-form-urlencoded
+
+    POST connect/token
+
+    grant_type=client_credentials&
+    scope=iSHARE&
+    client_id=EU.EORI.NL000000001&
+    client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
+    client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1YyI6WyJNSUlFZ1RDQ0FtbWdBd0lCQWdJSU45VmlDRGkzQndzd0RRWUpLb1pJaHZjTkFRRUxCUUF3U0RFWk1CY0dBMVVFQXd3UWFWTklRVkpGVkdWemRFTkJYMVJNVXpFTk1Bc0dBMVVFQ3d3RVZHVnpkREVQTUEwR0ExVUVDZ3dHYVZOSVFWSkZNUXN3Q1FZRFZRUUdFd0pPVERBZUZ3MHhPVEF5TVRVeE1UUTJNVFZhRncweU1UQXlNVFF4TVRRMk1UVmFNRUl4RlRBVEJnTlZCQU1NREVGQ1F5QlVjblZqYTJsdVp6RWNNQm9HQTFVRUJSTVRSVlV1UlU5U1NTNU9UREF3TURBd01EQXdNVEVMTUFrR0ExVUVCaE1DVGt3d2dnRWlNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0SUJEd0F3Z2dFS0FvSUJBUUMwTzRoVWhEK1ZvT0tWSVpTTk1OVGZ6YzBPMmtZaitaenBRRUFCWkd0UHR5MGtLUEplcDArbzV4c3RvdTFLK1V4dkhmeEVwSHhIR1RkdHFadWMyOExoVTRDZUNnb2VETURUK0NIUzNOb3NpRVNRTXdoL1paZVRjOS9lS0NvNTY5R0NuKzJYdFRpR1NwQlN3TVNXcU5IZ3BBWllLZEhyVC9rRU1JeVRLb2F1dWlLUThjVXA3b3c3bVp6LzlLK3FWM3M5TDAzMFc4SWF3TEpCSksvMmFwQXQ1amgxajQvbUY3ZjBxOHpoemhyQzh2MDFQTGxaZHVUempqQnJlN216K3lpL3ZsWXovZWFwMGVZVGpoeElhdHlWOUZGd2xtaTRGQzFDTmNNdExoOG5zaUpvZTVjQm0xM0xLYlFGdTNHWUg3Nm9lTFp2V3FiUGJwMTFteGxIYS9LZEFnTUJBQUdqZFRCek1Bd0dBMVVkRXdFQi93UUNNQUF3SHdZRFZSMGpCQmd3Rm9BVUZqem5JT25XbE84ZjVhTHh1UHkrNnQ4c040RXdFd1lEVlIwbEJBd3dDZ1lJS3dZQkJRVUhBd0V3SFFZRFZSME9CQllFRkFQSCs4VXJZaVZMWGFLUFJHZmxrQStjdXNRN01BNEdBMVVkRHdFQi93UUVBd0lGb0RBTkJna3Foa2lHOXcwQkFRc0ZBQU9DQWdFQVlsNXRXSDBZdFlTOUp5cXlsWkpXb21BNTVTaEtsbGFCUmN2cm82Q0h4bGxKV0hvMHFDOVpUTWN2Q3l3TXYxNFZKeVFkNmVGWnFjVnRPbHVHclJaQmtsSDlBYW5rb3ZwMkpMYXFjRDc5dDFDeXVYWm5JelRGbC9Ca01zRTZ3bEFKWFkvc2Fybm94ZWllalA0RS9FZi8wZXVJRnZCYUlDQ0YrS2QyV0pZYmJuMFd5MGRINDg0UUpiSHlNdFZmcjQyb0lwVU5WdUxTdTg0eUtZQWVtOUpCdVlUcDNZMEsyaGlFQVcvYk9LRHZ2SGV0VmY1ZnU2NnlmZWtEWDUzajNOS2lGSkNYUzJyS0lab0R1TUZ1eHBTeVZrUzJrYldrMSs1Sm95N3FPU05BTlJGUGxwSGNnekxRWnA4SHJndmhzbWhJdDFWVFZZa3l4Y2Q4cVhBbGh3cVZnT3E1TmdMeGtxdWw5aE5NR2lNN3NxK0g3M1EvRmk4aWY3Z1A4SVZBU3pRR3d1SGcyWjg3aWI2QTJ2b24wZlJKWnEzZkl1YkhveEk2M0FUd2ZjUks4NnkxNzJ4YkZFM1ZVMGR1TjF0STVaMFRDZzBHQUpZdEpwYm52ZXhJdDVsazVGSWs0VGh2UjBMOG1OTHkxRFVhMTFOK0VNeGtxYmZxbFR1ckI4WmczQ1kvUWFTS21YWTVDTVV3V2VFQlhSSGh5ZmtaUTVqUFBVSHJGYW95T1JYOHAxRXJZRGt0QjFLOW80am11RVZwQjMzY3ZnWUJFaUF5VjV6NDQyNkZ1VkNNYkhhRkRWN2lLVzllQmxYb3hlWm80WFg4K2pYeVNMNUdXOFh3TlJUSzVjNHZXMDJRM1ZKeVlWZTV1bWVzdHNLUStMUjhpQXpvVVNyZUsxOCtKa0FqQUpVPSJdfQ.eyJpc3MiOiJFVS5FT1JJLk5MMDAwMDAwMDAxIiwic3ViIjoiRVUuRU9SSS5OTDAwMDAwMDAwMSIsImp0aSI6ImE1MjJjZWZkNGNmNjQyMWE4ZGUzOGJjYjBjMDhlYjliIiwiaWF0IjoxNTU2MDM0NzM0LCJuYmYiOjE1NTYwMzQ3MzQsImV4cCI6MTU1NjAzNDc2NCwiYXVkIjoiRVUuRU9SSS5OTDAwMDAwMDAwMCJ9.SU59EXhAukbDVP0Y8Yb_1-5Za7QCgAtgq_bh9qRKNY0t3P7nodr2b6ue2DqmIZ_bvysC77zX01QCiCCT3vT7iU4ee4HINMP9gsujoNC0L1ONL2twoJeE91hWUke8dBL9m_ipP0x5-XivQAdS9vJTHQu1A_m5VB0O_XD4JGLwrwjD2d-UE4Fhyy4ilKSPKFpqhoAi2qPkmonZki-RaYoPkrq49LW_v8OVKW7yFJvEDIwph0hEcWxl0udyeu3Cy35NWMnLZdu6gp2f4yxOq3FPrufO5bT0aihioI04V8avggzVJdVcrDTK9Q0Hzhs-22VamkncUZqPvRmo_uwypNHFBg
+
+(URL encoding removed, and line breaks added for readability)
+
+Response
+--------
+
+Headers
+~~~~~~~
+
+``Content-Type``
+    | **String**.
+    | Defines response body content type. MUST be equal to *application/json*.
+
+HTTP status codes
+~~~~~~~~~~~~~~~~~
+
+200 OK
+    | When a valid request is sent an OK result should be returned.
+
+400 Bad Request
+    | When invalid request is sent a Bad Request result should be returned.
+
+Parameters
+~~~~~~~~~~
+
+``access_token``
+    | **String**.
+    | The access token which will be used to access endpoints that require authorization.
+
+``token_type``
+    | **String**.
+    | Since we follow OAuth 2.0 specification value should be equal to *Bearer*.
+
+``expires_in``
+    | **Integer**.
+    | Access token expiration time in seconds. Should be *3600*.
+
+200 OK Example
+~~~~~~~~~~~~~~
+
+::
+
+    < Content-Type: application/json
+
+    {
+      "access_token": "aW2ys9NGE8RjHPZ4mytQivkWJO5HGQCYJ7VyMBGGDLIOw",
+      "token_type": "Bearer",
+      "expires_in": 3600
+    }
+
+(Line breaks added for readability)

conf.py

@@ -0,0 +1,75 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- 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('_ext'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'dev.ishareworks.org'
+copyright = '2020, iSHARE'
+author = 'iSHARE'
+
+# The full version, including alpha/beta/rc tags
+release = '1.0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+import sphinx_rtd_theme
+
+# 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_rtd_theme',
+  'edit_on_github'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_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']
+
+
+# -- 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_options = {
+    'canonical_url': '',
+    'logo_only': True,
+    'display_version': False,
+    'sticky_navigation': True,
+    'navigation_depth': -1,
+    'collapse_navigation': False
+}
+
+html_logo = '_static/logo.svg'
+
+html_favicon = '_static/favicon.ico'
+
+# 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']
+
+edit_on_github_project = 'iSHAREScheme/Documentation'
+edit_on_github_branch = 'master'