Add detection of deprecated URIs

Also, trim `ResourceBlock` related URIs from the URI list for brevity, but add a note to the URI list to explain that.

doc-generator/doc_formatter/csv_generator.py

@@ -288,7 +288,7 @@ def add_description(self, text):
         pass
 
 
-    def add_uris(self, uris):
+    def add_uris(self, uris, urisDeprecated):
         """ CSV omits URIs """
         pass
 

doc-generator/doc_formatter/doc_formatter.py

@@ -178,7 +178,7 @@ def add_deprecation_text(self, deprecation_text):
         raise NotImplementedError
 
 
-    def add_uris(self, uris):
+    def add_uris(self, uris, urisDeprecated):
         """ Add the uris """
         raise NotImplementedError
 
@@ -586,7 +586,7 @@ def generate_output(self):
                 self.add_deprecation_text(details['deprecated'])
 
             if len(uris):
-                self.add_uris(uris)
+                self.add_uris(uris, details['urisDeprecated'])
                 self.current_uris = uris
             else:
                 self.current_uris = []

doc-generator/doc_formatter/html_generator.py

@@ -972,11 +972,26 @@ def add_deprecation_text(self, deprecation_text):
         self.this_section['deprecation_text'] = depr_text
 
 
-    def add_uris(self, uris):
+    def add_uris(self, uris, urisDeprecated):
         """ Add the URIs (which should be a list) """
         uri_strings = []
+
+        for i in range(len(uris)):
+            if uris[i] in urisDeprecated:
+                uris[i] += _(" (deprecated)")
+
+        # if resource block-related URIs are in the list, omit them for brevity
+        has_resource_block_uris = False
         for uri in sorted(uris, key=str.lower):
-            uri_strings.append('<li class="hanging-indent">' + self.format_uri(uri) + '</li>')
+            if 'ResourceBlocks' in uri:
+                has_resource_block_uris = True
+            else:
+                uri_strings.append('<li class="hanging-indent">' + self.format_uri(uri) + '</li>')
+
+        # if resource block-related URIs have been trimmed, add a note 
+        if has_resource_block_uris:
+            uri_strings.append('<li class="hanging-indent">' +
+                _("* Note: Resource block-related URIs have been omitted from this list") + '\n</li>')
 
         uri_block = '<ul class="nobullet">' + '\n'.join(uri_strings) + '</ul>'
         uri_content = '<h4>' + _('URIs:') + '</h4>' + uri_block

doc-generator/doc_formatter/markdown_generator.py

@@ -944,11 +944,22 @@ def add_deprecation_text(self, deprecation_text):
         self.this_section['deprecation_text'] = depr_text + '\n'
 
 
-    def add_uris(self, uris):
+    def add_uris(self, uris, urisDeprecated):
         """ Add the URIs (which should be a list) """
+        has_resource_block_uris = False
         uri_block = self.format_head_three(_('URIs'), self.level)
         for uri in sorted(uris, key=str.lower):
-            uri_block += "\n" + self.format_uri(uri) + "<br>"
+            if 'ResourceBlocks' in uri:   # trim out resource block-related URIs
+                has_resource_block_uris = True
+                continue
+            if uri in urisDeprecated:
+                uri_block += "\n" + self.format_uri(uri) + _(" (deprecated)") +"<br>"
+            else:
+                uri_block += "\n" + self.format_uri(uri) + "<br>"
+
+        if has_resource_block_uris:  # if URIs were trimmed, add a note
+            uri_block += "\n" + _("* Note: Resource block-related URIs have been omitted from this list") + "<br>"
+
         self.this_section['uris'] = uri_block + "\n"
 
 

doc-generator/doc_formatter/property_index_generator.py

@@ -541,7 +541,7 @@ def add_description(self, text):
         """ This is for the schema description. We don't actually use this. """
         pass
 
-    def add_uris(self, uris):
+    def add_uris(self, uris, urisDeprecated):
         """ omit URIs """
         pass
 

doc-generator/doc_generator.py

@@ -407,6 +407,7 @@ def generate_docs(self, level=0):
                     warnings.warn('Unable to process files for %(uri)s' % {'uri': normalized_uri})
                 continue
             data['uris'] = schema_data[normalized_uri].get('_uris', [])
+            data['urisDeprecated'] = schema_data[normalized_uri].get('_urisDeprecated', [])
 
             if normalized_uri.endswith('Collection.json'):
                 [preamble, collection_name] = normalized_uri.rsplit('/', 1)
@@ -605,6 +606,10 @@ def group_files(self, files):
             if 'uris' in data:
                 # Stash these in the unversioned schema_data.
                 all_schemas[normalized_uri]['_uris'] = data['uris']
+
+            if 'urisDeprecated' in data:
+                # Stash the deprecated URIs as well
+                all_schemas[normalized_uri]['_urisDeprecated'] = data['urisDeprecated']
 
             if len(ref_files):
                 # Add the _is_versioned_schema and  is_collection_of hints to each ref object