Merge branch 'master' into add-code-of-conduct-1

openreferral · Jan 24, 2023 · 7b7bf37 · 7b7bf37
2 parents df057a7 + 342b69e
commit 7b7bf37
Show file tree

Hide file tree

Showing 27 changed files with 395 additions and 303 deletions.
diff --git a/.github/workflows/build_database.yml b/.github/workflows/build_database.yml
@@ -27,8 +27,10 @@ jobs:
       with:
         python-version: 3.9
         architecture: x64
+    # We also need mysql-client-8.0 BUT it is installed my default
+    #    and if we explicitly ask for it to be safe we sometimes get package errors
     - name: Install Ubuntu libs
-      run: sudo apt-get install -y graphviz graphviz-dev mysql-client-8.0
+      run: sudo apt-get install -y graphviz graphviz-dev
     - name: Install Python libs
       run: pip install -r requirements.txt
     - name: Install Python Libs for DB work

diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,6 @@
 .ve
-/docs/assets/entity_relationship_diagram.svg
-/docs/assets/entity_relationship_diagram_core_tables.svg
+/docs/extras/_images/entity_relationship_diagram.svg
+/docs/extras/_images/entity_relationship_diagram_core_tables.svg
 /examples/*/datapackage.json
 /tmp_datapackage_for_database_schemas/*.json
 /tmp_datapackage_for_database_schemas/*.csv
diff --git a/LICENSE b/LICENSE
@@ -1,12 +1,12 @@
-The Human Services Data Specification and associated documentation are licensed under the Creative Commons Attribution Share-Alike 4.0 license.
+The Human Services Data Specification (HSDS) and associated documentation are licensed under the Creative Commons Attribution Share-Alike 4.0 license.
 
 A summary of this license is available at https://creativecommons.org/licenses/by/4.0/
 
 Unless otherwise stated, contributions are copyright of the Open Referral project. 
 
 Our preferred form of attribution is "Human Services Data Specification: an Open Referral resource (https://openreferral.org/)"
 
-The Open Referral project is stewarded by Greg Bloom.
+The Open Referral project is stewarded under the leadership of Greg Bloom, with fiscal sponsorship from Aspiration, a 501c3 organization. HSDS and all associated documentation are the intellectual property of Aspiration.
 
 Version 1.0 of the specification is also available under a CC0 Public Domain Dedication
 

diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
@@ -9,4 +9,8 @@
     overflow: visible !important;
 }
 
-
+/* To fit the ERD's on HSDS/Logical Model page properly. It's the same content as the theme does for img's. */
+.rst-content svg {
+    max-width: 100%;
+    height: auto;
+}
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -10,7 +10,7 @@
   _paq.push(['trackPageView']);
   _paq.push(['enableLinkTracking']);
   (function() {
-    var u="//mon.opendataservices.coop/piwik/";
+    var u="//mon.opendataservices.coop/";
     _paq.push(['setTrackerUrl', u+'piwik.php']);
     _paq.push(['setSiteId', '16']);
     var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];

diff --git a/docs/conf.py b/docs/conf.py
@@ -54,7 +54,7 @@
 
 # General information about the project.
 project = 'Open Referral Data Specifications'
-copyright = '2016, Open Referral'
+copyright = 'Open Referral'
 author = 'Open Referral'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -85,7 +85,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_images/.gitkeep']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -146,6 +146,10 @@
 
 html_js_files = ["custom.js"]
 
+html_theme_options = {
+    'titles_only': True
+}
+
 # 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.
@@ -184,7 +188,7 @@
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 #
-# html_extra_path = []
+html_extra_path = ['extras']
 
 # If not None, a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
@@ -363,7 +367,10 @@
 # texinfo_no_detailmenu = False
 
 
+# MyST configuration
 
+# Autogenerate anchors for Markdown headings (h1, h2)
+myst_heading_anchors = 2
 
 from docutils.parsers.rst import directives
 from docutils.parsers.rst import Directive
@@ -464,9 +471,10 @@ def __init__(self,widths):
     html_color_header_for_table[core_table] = '#77DD77'
 jts_erd.save_svg(
         datapackage,
-        'assets/entity_relationship_diagram.svg',
+        'extras/_images/entity_relationship_diagram.svg',
         display_columns=True,
         display_indexes=True,
+        display_tooltips=False,
         fontname="Lato",
         html_color_header='#AEC6CF',
         html_color_header_for_table=html_color_header_for_table,
@@ -475,7 +483,7 @@ def __init__(self,widths):
         default_namespace_name='human_services_data',
         rankdir='RL',
     )
-openreferral.svg_utils.insert_style_rule_to_svg('assets/entity_relationship_diagram.svg', svg_style_rule)
+openreferral.svg_utils.insert_style_rule_to_svg('extras/_images/entity_relationship_diagram.svg', svg_style_rule)
 
 #---- Core Tables ERD
 
@@ -494,21 +502,24 @@ def __init__(self,widths):
 # Write ERD
 jts_erd.save_svg(
     datapackage_core_tables_only,
-    'assets/entity_relationship_diagram_core_tables.svg',
+    'extras/_images/entity_relationship_diagram_core_tables.svg',
     display_columns=True,
     display_indexes=True,
+    display_tooltips=False,
     fontname="Lato",
     html_color_header='#77DD77',
     html_color_default='#DDDDDD',
     html_color_highlight='#DDDDDD',
     default_namespace_name='human_services_data',
     rankdir='RL',
 )
-openreferral.svg_utils.insert_style_rule_to_svg('assets/entity_relationship_diagram_core_tables.svg', svg_style_rule)
+openreferral.svg_utils.insert_style_rule_to_svg('extras/_images/entity_relationship_diagram_core_tables.svg', svg_style_rule)
 
 def setup(app):
     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/extras/_images/.gitkeep b/docs/extras/_images/.gitkeep
diff --git a/docs/hsda/index.md b/docs/hsda/index.md
@@ -16,7 +16,7 @@ HSDA is one of the Open Referral specifications, and builds on [HSDS](hsds). Ope
 
     HSDA provides a family of OpenAPI specifications that can be used as a blueprint for the design or adaptation of API platforms to provide read or read/write access to information on organizations, services, locations and the details about them.
 
-    The core API protocol can be used by mobile apps, websites and other services to access individual resources, or listings. Providers can also support updates via API if they choose. In conjuction with the search protocol, this provides most of the functionality needed for simple access and exchange of data.
+    The core API protocol can be used by mobile apps, websites and other services to access individual resources, or listings. Providers can also support updates via API if they choose. In conjunction with the search protocol, this provides most of the functionality needed for simple access and exchange of data.
 
     More complex data synchronization between distributed systems is supported through the additional protocols. 
 

diff --git a/docs/hsds/classifications.md b/docs/hsds/classifications.md
@@ -1,6 +1,10 @@
 Classifications, Attributes & Taxonomies
 ========================================
 
+```{note}
+This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+```
+
 HSDS allows any major entity to have attributes attached. These attributes can be either properties of the entity, or classifications of the entity. 
 
 For _services_, the _service_taxonomy_ table is used for this.
@@ -160,5 +164,3 @@ And finally, we use the other_attributes table to link the program with the appr
 +----+---------+-----------+------------------+
 ```
 
-#### This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
-
diff --git a/docs/hsds/detail_dates.md b/docs/hsds/detail_dates.md
diff --git a/docs/hsds/extending.md b/docs/hsds/extending.md
@@ -1,6 +1,10 @@
 Extending HSDS
 ==============
 
+```{note}
+This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+```
+
 HSDS provides a common core for describing services, and includes a range of common fields, many of which are optional.
 
 However, service provision is usually local, and so in a particular context there's likely to be fields that aren't relevant, and information that's important but isn't included in HSDS.
@@ -44,4 +48,3 @@ It's good practice to create a schema to reflect your data when extending or con
 Extending the standard is a way to try out potential changes to the standard, so extensions play an important part in preparing for future releases. 
 
 
-#### This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
diff --git a/docs/hsds/formatting.md b/docs/hsds/formatting.md
@@ -1,5 +1,5 @@
-Producing and Sharing Compliant Data
-====================================
+Formatting & Packaging
+======================
 
 HSDS uses the Frictionless Data project's [Data Package specification.](https://specs.frictionlessdata.io/)
 
@@ -32,4 +32,4 @@ Because of the variety of addressing systems, every field is composed of alphanu
 
 ### Description Field Formatting
 
-The description field may include HTML or Markdown tags.
+The description field may include HTML or Markdown tags.
diff --git a/docs/hsds/identifiers.md b/docs/hsds/identifiers.md
@@ -1,6 +1,10 @@
 Identifiers
 ===========
 
+```{note}
+This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+```
+
 The HSDS specification contains a lot of identifiers; this guide explains what they're for and what good practice looks like around using them. 
 
 ## id fields
@@ -9,5 +13,3 @@ Each table in HSDS has an id field; as HSDS is designed to map onto a relational
 
 The organization table is a special case; because identifying organizations is a complex area, the standard stipulates that UUIDs must be used so as to prevent the use of external identifiers. This avoids, for example, issues such as companies changing their legal status and causing data quality issues as a result.
 
-
-#### This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
diff --git a/docs/hsds/index.md b/docs/hsds/index.md
diff --git a/docs/hsds/logical_model.md b/docs/hsds/logical_model.md
@@ -64,17 +64,17 @@ E.g. a phone number applies to the service OR the organisation OR the service_at
 
 ## ER Diagram
 
-*Click to enlarge*
-
 ```{eval-rst}
-.. image:: ../assets/entity_relationship_diagram_core_tables.svg
-   :target: ../../_images/entity_relationship_diagram_core_tables.svg
+
+`[enlarge] <../../_images/entity_relationship_diagram_core_tables.svg>`_
+
+.. raw:: html
+    :file: ../extras/_images/entity_relationship_diagram_core_tables.svg
+    
 ```
 
 ## ER Diagram (Full version)
 
-*Click to enlarge*
-
 <div style="background-color: #77DD77;">
 
 Core tables are shown in green.
@@ -88,7 +88,10 @@ Other tables are shown in blue.
 </div>
 
 ```{eval-rst}
-.. image:: ../assets/entity_relationship_diagram.svg
-   :target: ../../_images/entity_relationship_diagram.svg
-```
 
+`[enlarge] <../../_images/entity_relationship_diagram.svg>`_
+
+.. raw:: html
+    :file: ../extras/_images/entity_relationship_diagram.svg
+    
+```
diff --git a/docs/hsds/producing_sharing.md b/docs/hsds/producing_sharing.md
@@ -1,5 +1,9 @@
-Producing and Sharing Compliant Data
-====================================
+Publication Guidance
+====================
+
+```{note}
+This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+```
 
 ### Guidance on Mapping Fields and Values
 
@@ -16,4 +20,6 @@ Source data may or may not map directly to the HSDS. Guidelines are listed below
 
 The files and their associated attributes are [listed on the reference page](reference.md).
 
-#### This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+### Sharing Your Changes
+
+If the additional information that you're providing is of use to a wider community, then it may be helpful to share details with others. See the [Extending HSDS](extending.md) for information on how to do that. 
diff --git a/docs/hsds/sample_data.md b/docs/hsds/sample_data.md
@@ -4,8 +4,11 @@
 
 # Sample data
 
+```{note}
+This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.
+```
+
 We maintain [a repository of example HSDS data here](https://github.com/openreferral/sample-data).
 
 If you have example of HSDS data to share, please get in touch.
 
-#### This page is *non-normative*, which means that it doesn't form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.