Merge pull request #505 from DMTF/fix-489

Added support for intra-document links for Markdown output

Author: mraineri

doc-generator/doc_formatter/csv_generator.py

@@ -287,6 +287,9 @@ def add_description(self, text):
         """  CSV omits schema description """
         pass
 
+    def add_deprecation_text(self, deprecation_text):
+        """ CSV omits deprecation text """
+        pass
 
     def add_uris(self, uris, urisDeprecated):
         """ CSV omits URIs """

doc-generator/doc_formatter/doc_formatter.py

@@ -1053,7 +1053,7 @@ def extend_property_info(self, schema_ref, prop_info):
                                 if 'redfish.dmtf.org/schemas/v1/odata' in from_schema_uri:
                                     from_schema_uri = 'http://' + is_collection_of
 
-                                link_detail = (_('Link to Collection of %(schema_links)s. See the %(schema_name)s schema for details.')
+                                link_detail = (_('Link to Collection of %(schema_name)s. See the %(schema_links)s schema for details.')
                                                    % {'schema_links': self.link_to_own_schema(is_collection_of, from_schema_uri),
                                                           'schema_name': ref_schema_name})
 

doc-generator/doc_formatter/markdown_generator.py

@@ -64,7 +64,11 @@ def format_property_row(self, schema_ref, prop_name, prop_info, prop_path=[], in
 
         This may include embedded objects with their own properties.
         """
+        if not in_schema_ref:
+            in_schema_ref = schema_ref
 
+        schema_anchor = self.traverser.get_schema_name(in_schema_ref)
+        
         formatted = []     # The row itself
 
         within_action = prop_path == ['Actions']
@@ -211,7 +215,14 @@ def format_property_row(self, schema_ref, prop_name, prop_info, prop_path=[], in
             if formatted_details['has_direct_prop_details'] and not formatted_details['has_action_details']:
                 # If there are prop_details (enum details), add a note to the description:
                 if has_enum:
-                    text_descr = _('For the possible property values, see %(link)s in Property details.') % {'link': prop_name}
+                    if self.markdown_mode == 'slate' or not schema_anchor:
+                        text_descr = (_('For the possible property values, see %(link)s in Property details.') %
+                                      {'link': prop_name})
+                    else:
+                        anchor = schema_anchor.lower() + '-' + prop_name.lower()
+                        text_descr = (_('For the possible property values, see %(link)s in Property details.') %
+                                      {'link': '[' + prop_name + '](#' + anchor + ')'})
+                    
                 else:
                     text_descr = _('For more information about this property, see Property details.')
                 formatted_details['descr'] += ' ' + self.formatter.italic(text_descr)
@@ -648,9 +659,19 @@ def format_as_prop_details(self, prop_name, prop_description, rows):
         return "\n".join(contents)
 
 
-    def link_to_own_schema(self, schema_ref, schema_full_uri):
-        """Format a reference to a schema."""
-        result = super().link_to_own_schema(schema_ref, schema_full_uri)
+    def link_to_own_schema(self, schema_ref, schema_uri):
+        schema_name = self.traverser.get_schema_name(schema_ref)
+        if not schema_name:
+            schema_name = schema_ref
+
+        if self.markdown_mode == 'slate':
+            return self.formatter.italic(schema_name)
+            
+        if self.is_documented_schema(schema_ref):
+            result = '[' + schema_name + '](#' + schema_name.lower() + ')'
+        else:
+            result = '[' + schema_name + '](' + schema_uri + ')'
+
         return self.formatter.italic(result)
 
 
@@ -665,7 +686,13 @@ def emit(self):
         contents = []
 
         for section in self.sections:
+            schema_name = section.get('schema_name')
+
             contents.append(section.get('heading'))
+            # if there are version numbers in the headings, add an anchor tag for the section using only the section name
+            if schema_name and not self.markdown_mode == 'slate' and not self.config.get('omit_version_in_headers'):
+                contents.append('<a name="' + schema_name.lower() + '"></a>')
+
             if section.get('release_history'):
                 contents.append(section['release_history'])
             if section.get('conditional_requirements'):
@@ -726,6 +753,11 @@ def emit(self):
                 detail_names.sort(key=str.lower)
                 for detail_name in detail_names:
                     contents.append(self.format_head_four(detail_name, 0))
+                    
+                    # add section/schema-specific anchor tag
+                    if schema_name and not self.markdown_mode == 'slate':
+                        contents.append('<a name="' + schema_name.lower() + '-' + detail_name.lower() + '"></a>')
+                    
                     det_info = section['property_details'][detail_name]
 
                     if len(det_info) == 1:

doc-generator/locale/TEST/LC_MESSAGES/doc_generator.mo

@@ -193,8 +193,8 @@ msgid "Contains a link to a resource."
 msgstr "CONTAINS A LINK TO A RESOURCE."
 
 #: doc_formatter/doc_formatter.py:920
-msgid "Link to Collection of %(schema_links)s. See the %(schema_name)s schema for details."
-msgstr "LINK TO COLLECTION OF %(schema_links)s. SEE THE %(schema_name)s SCHEMA FOR DETAILS."
+msgid "Link to Collection of %(schema_name)s. See the %(schema_links)s schema for details."
+msgstr "LINK TO COLLECTION OF %(schema_name)s. SEE THE %(schema_links)s SCHEMA FOR DETAILS."
 
 #: doc_formatter/doc_formatter.py:927
 msgid "Link to another %(name)s resource."

doc-generator/locale/TEST/LC_MESSAGES/doc_generator.po

@@ -225,7 +225,7 @@ msgid "Contains a link to a resource."
 msgstr ""
 
 #: doc_formatter/doc_formatter.py:977
-msgid "Link to Collection of %(schema_links)s. See the %(schema_name)s schema for details."
+msgid "Link to Collection of %(schema_name)s. See the %(schema_links)s schema for details."
 msgstr ""
 
 #: doc_formatter/doc_formatter.py:984

doc-generator/locale/doc_generator.pot

@@ -214,7 +214,7 @@ msgid "Contains a link to a resource."
 msgstr ""
 
 #: doc_formatter/doc_formatter.py:971
-msgid "Link to Collection of %(schema_links)s. See the %(schema_name)s schema for details."
+msgid "Link to Collection of %(schema_name)s. See the %(schema_links)s schema for details."
 msgstr ""
 
 #: doc_formatter/doc_formatter.py:978