Merge branch '1.1.1' of https://github.com/openreferral/specification …

…into 1.1.1
openreferral · Dec 20, 2017 · 4c93993 · 4c93993
2 parents 54f1588 + 5511f13
commit 4c93993
Show file tree

Hide file tree

Showing 38 changed files with 722 additions and 189 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "api-specification"]
+	path = api-specification
+	url = https://github.com/openreferral/api-specification.git
diff --git a/README.md b/README.md
@@ -4,6 +4,8 @@ Human Services Data Specification defines a minimal set of data for publishing m
 
 A detailed FAQ about the project is [found here](http://docs.openreferral.org/en/latest/faq), and additional information about the Open Referral Initiative is available at [https://openreferral.org](https://openreferral.org)
 
+This project also integrates documentation for the [Human Services Data API specification](https://github.com/openreferral/api-specification) which builds upon HSDS.
+
 ## License
 
 The Human Services Data Specification and its documentation are [licensed](LICENSE) under the Creative Commons Attribution-ShareAlike (CC BY-SA) license.
@@ -22,16 +24,38 @@ Other branches are not built automatically, but can be configured by admin's of
 
 ### Building locally
 
-Assuming a unix based system with Python 3 installed:
+Assuming a unix based system with Python 3 installed, set up an environment:
 
 ```
 python3 -m venv .ve    
 source .ve/bin/activate
 pip install -r requirements.txt
+```
+
+Then pull in the submodule for the api-documentation. 
+
+```
+git submodule init
+git submodule update
+```
+
+The update command should be re-run whenever there are updates to the api-specification repository. 
+
+To build the docs:
+
+```
 cd docs
 make dirhtml
 ```
 
+You can also use sphinx-autobuild to have an auto-refreshing local build.
+
+```
+pip install sphinx-autobuild
+cd docs
+sphinx-autobuild . _build
+```
+
 ### Translations
 
 Translations wil be done using this transifex project - https://www.transifex.com/OpenDataServices/open-referral-1-0/

diff --git a/api-specification b/api-specification
diff --git a/docs/_static/custom.js b/docs/_static/custom.js
@@ -0,0 +1,3 @@
+$(function() {
+    $("tr:contains('Deprecated)') td").css("background","lightGrey").css("color","grey")
+});
diff --git a/docs/_static/swagger/favicon-32x32.png b/docs/_static/swagger/favicon-32x32.png
diff --git a/docs/_static/swagger/index.html b/docs/_static/swagger/index.html
@@ -0,0 +1,95 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Swagger UI</title>
+  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
+  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
+  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  <style>
+    html
+    {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *,
+    *:before,
+    *:after
+    {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+
+<body>
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
+  <defs>
+    <symbol viewBox="0 0 20 20" id="unlocked">
+          <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="locked">
+      <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="close">
+      <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="large-arrow">
+      <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 20 20" id="large-arrow-down">
+      <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
+    </symbol>
+
+
+    <symbol viewBox="0 0 24 24" id="jump-to">
+      <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
+    </symbol>
+
+    <symbol viewBox="0 0 24 24" id="expand">
+      <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
+    </symbol>
+
+  </defs>
+</svg>
+
+<div id="swagger-ui"></div>
+
+<script src="./swagger-ui-bundle.js"> </script>
+<script src="./swagger-ui-standalone-preset.js"> </script>
+<script>
+window.onload = function() {
+
+  // Build a system
+  const ui = SwaggerUIBundle({
+    url: "http://petstore.swagger.io/v2/swagger.json",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  })
+
+  window.ui = ui
+}
+</script>
+</body>
+
+</html>
diff --git a/docs/_static/swagger/oauth2-redirect.html b/docs/_static/swagger/oauth2-redirect.html
@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en-US">
+<body onload="run()">
+</body>
+</html>
+<script>
+    'use strict';
+    function run () {
+        var oauth2 = window.opener.swaggerUIRedirectOauth2;
+        var sentState = oauth2.state;
+        var redirectUrl = oauth2.redirectUrl;
+        var isValid, qp, arr;
+
+        if (/code|token|error/.test(window.location.hash)) {
+            qp = window.location.hash.substring(1);
+        } else {
+            qp = location.search.substring(1);
+        }
+
+        arr = qp.split("&")
+        arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';})
+        qp = qp ? JSON.parse('{' + arr.join() + '}',
+                function (key, value) {
+                    return key === "" ? value : decodeURIComponent(value)
+                }
+        ) : {}
+
+        isValid = qp.state === sentState
+
+        if ((
+          oauth2.auth.schema.get("flow") === "accessCode"||
+          oauth2.auth.schema.get("flow") === "authorizationCode"
+        ) && !oauth2.auth.code) {
+            if (!isValid) {
+                oauth2.errCb({
+                    authId: oauth2.auth.name,
+                    source: "auth",
+                    level: "warning",
+                    message: "Authorization may be unsafe, passed state was changed in server Passed state wasn't returned from auth server"
+                });
+            }
+
+            if (qp.code) {
+                delete oauth2.state;
+                oauth2.auth.code = qp.code;
+                oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
+            } else {
+                oauth2.errCb({
+                    authId: oauth2.auth.name,
+                    source: "auth",
+                    level: "error",
+                    message: "Authorization failed: no accessCode received from the server"
+                });
+            }
+        } else {
+            oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
+        }
+        window.close();
+    }
+</script>
diff --git a/docs/_static/swagger/swagger-ui-bundle.js b/docs/_static/swagger/swagger-ui-bundle.js
diff --git a/docs/_static/swagger/swagger-ui-bundle.js.map b/docs/_static/swagger/swagger-ui-bundle.js.map
diff --git a/docs/_static/swagger/swagger-ui-standalone-preset.js b/docs/_static/swagger/swagger-ui-standalone-preset.js
diff --git a/docs/_static/swagger/swagger-ui-standalone-preset.js.map b/docs/_static/swagger/swagger-ui-standalone-preset.js.map
diff --git a/docs/_static/swagger/swagger-ui.css b/docs/_static/swagger/swagger-ui.css
diff --git a/docs/_static/swagger/swagger-ui.css.map b/docs/_static/swagger/swagger-ui.css.map
diff --git a/docs/_static/swagger/swagger-ui.js b/docs/_static/swagger/swagger-ui.js
diff --git a/docs/_static/swagger/swagger-ui.js.map b/docs/_static/swagger/swagger-ui.js.map
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
@@ -10,22 +10,3 @@
 }
 
 
-.wy-table-responsive th:nth-of-type(1) {
-    width:10%;
-}
-
-.wy-table-responsive th:nth-of-type(2) {
-    width:10%;
-}
-
-.wy-table-responsive th:nth-of-type(3) {
-    width:60%;
-}
-
-.wy-table-responsive th:nth-of-type(4) {
-    width:10%;
-}
-
-.wy-table-responsive th:nth-of-type(5) {
-    width:10%;
-}
diff --git a/docs/assets/hsda-miami.png b/docs/assets/hsda-miami.png
diff --git a/docs/assets/hsds_er_diagram_v1.1.png b/docs/assets/hsds_er_diagram_v1.1.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -33,7 +33,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinxcontrib.openapi', 'sphinxcontrib.opendataservices']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -56,8 +56,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'Open Referral'
-copyright = '2017, Open Referral. CC 4.0 BY SA'
+project = 'Open Referral Data Specifications'
+copyright = '2016, Open Referral'
 author = 'Open Referral'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -131,22 +131,21 @@
 # html_theme = 'alabaster'
 html_static_path = ['_static']
 
-import os
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
   import sphinx_rtd_theme
   html_theme = 'sphinx_rtd_theme'
   html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
   html_style = 'css/custom.css'
-else:
-  html_context = { 
+
+html_context = { 
     'css_files': [
         'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
         'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
         '_static/theme_overrides.css',
     ],
-  }
+}
 
 
 
@@ -289,7 +288,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'OpenReferral.tex', 'Open Referral Documentation',
+    (master_doc, 'OpenReferral.tex', 'Open Referral Data Specifications',
      'Open Referral', 'manual'),
 ]
 
@@ -331,7 +330,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'openreferral', 'Open Referral Documentation',
+    (master_doc, 'openreferral', 'Open Referral Data Specifications',
      [author], 1)
 ]
 
@@ -346,8 +345,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'OpenReferral', 'Open Referral Documentation',
-     author, 'OpenReferral', 'One line description of project.',
+    (master_doc, 'OpenReferral', 'Open Referral Data Specifications',
+     author, 'OpenReferral', 'Making it easy to share and find information about community resources',
      'Miscellaneous'),
 ]
 
@@ -414,6 +413,7 @@ def _wrap(cell):
                 self=None,
                 table_data=table_data,
                 col_widths=[1, 1],
+                widths='given',
                 header_rows=0,
                 stub_columns=0)
 
@@ -435,19 +435,24 @@ def _wrap(cell):
                 self=None,
                 table_data=table_data,
                 col_widths=[0.2,0.2,0.6,0.1,0.1],
+                widths='given',
                 header_rows=1,
                 stub_columns=0)
         return out
 
 directives.register_directive('jsontableschemainclude', JSONTableSchemaInclude)
 
 
-
-
 def setup(app):
     app.add_config_value('recommonmark_config', {
         #'url_resolver': lambda url: github_doc_root + url,
         'auto_toc_tree_section': 'Contents',
         'enable_eval_rst': True
         }, True)
     app.add_transform(AutoStructify)
+    app.add_javascript("custom.js")
+
+    import glob
+    global html_static_path
+    for file in glob.glob("../api-specification/_data/api-commons/*.yaml"):
+        html_static_path = html_static_path + [file]
diff --git a/docs/faq.md b/docs/faq.md
@@ -9,7 +9,7 @@ The Open Referral Initiative is a network of people and organizations working to
 
 Our **Human Service Data Specification** (AKA ‘the Open Referral format’) is a data exchange format that enables resource directory data to be shared among heterogeneous information systems.
 
-Open Referral’s ecosystem includes a range of open source tools and web applications that facilitate the flow of resource directory information. The **[the Ohana API](https://github.com/codeforamerica/ohana-api)** is an open source ‘reference implementation’ for the Open Referral format, and **[Ohana Web Search](https://github.com/codeforamerica/ohana-web-search)** (for example) is a resource locator website that works with the Ohana API (or compatible APIs). 
+Open Referral’s ecosystem includes a range of open source tools and web applications that facilitate the flow of resource directory information. The [the Ohana API](https://github.com/codeforamerica/ohana-api) is an open source ‘reference implementation’ for the Open Referral format, and [Ohana Web Search](https://github.com/codeforamerica/ohana-web-search) (for example) is a resource locator website that works with the Ohana API (or compatible APIs). 
 
 More tools are in development by members of Open Referral’s network, members of which are primarily assembled in [our Google Group](https://groups.google.com/forum/#!forum/openreferral).
 

diff --git a/docs/governance.md b/docs/governance.md
@@ -15,11 +15,11 @@ You can contribute to the development of these protocols in several ways:
 
 * **Add annotations to this documentation site using hypothes.is** - hypothes.is is an annotation service that is embedded in this site. (See the buttons in the top-right of this page.) Just highlight any text, and then use the pop-up box to add your comments. You will need to sign-up for a free account with [hypothes.is](https://hypothes.is/).
 
-* **Add a new issue or [engage with an existing issue on GitHub](https://github.com/openreferral/specification/issues/)**. We use this issue tracker to schedule all formal updates to the specification. Anyone can view and search the issues already raised. You will need to sign-up for a free GitHub account to comment or create issues.
+* Add a new issue or [engage with an existing issue on GitHub](https://github.com/openreferral/specification/issues/). We use this issue tracker to schedule all formal updates to the specification. Anyone can view and search the issues already raised. You will need to sign-up for a free GitHub account to comment or create issues.
 
-* **Join our [community forum](https://groups.google.com/forum/#!forum/openreferral)** where discussions around the specification are encouraged. 
+* Join our [community forum](https://groups.google.com/forum/#!forum/openreferral) where discussions around the specification are encouraged. 
 
-* **Attend our weekly office hours.** At noon EST each week (more or less!) the Open Referral leadership convenes to discuss any issues that participants bring up. We coordinate this in Slack; email [info@openreferral.org](mailto:info@openreferral.org) to request an invite.
+* Attend our weekly office hours. At noon EST each week (more or less!) the Open Referral leadership convenes to discuss any issues that participants bring up. We coordinate this in Slack; email [info@openreferral.org](mailto:info@openreferral.org) to request an invite.
 
 
 

diff --git a/docs/hsda/hsda-bulk.md b/docs/hsda/hsda-bulk.md
@@ -0,0 +1,21 @@
+```eval_rst
+.. _hsda-bulk:
+```
+# HSDA Bulk
+
+The HSDA bulk protocol is defined by [openapi-hsda-bulk.yaml](../static/openapi-hsda-bulk.yaml). The details below show the available methods and responses. 
+
+This is a service for handling bulk loading of data into any HSDA service, allowing each POST and PUT to be queued up as a job, and be run on schedule, or based upon other events.
+
+You can also [explore this using our OpenAPI viewer](../../_static/swagger/?url=../openapi-hsda-bulk.yaml). 
+
+```eval_rst
+.. warning::
+    
+    This is an experimental feature. Feedback is welcome to shape its further development.
+
+```
+
+```eval_rst
+.. openapi:: ../../api-specification/_data/api-commons/openapi-hsda-bulk.yaml
+```