Merge pull request #91 from IATI/incomplete-codelist-docs-v202

Deal with incomplete Codelists when generating element pages - V2.02

gen.py

@@ -48,7 +48,7 @@ def see_also(path, lang):
         mapping = json.load(open(os.path.join('IATI-Extra-Documentation', lang, standard, 'overview-mapping.json'))) # Loading this file is incredibly inefficient
         # Common 'simple' path e.g. iati-activities or budget/period-start
         # Using this prevents subpages of iati-activity using the activity file overview
-        simpler = len(path.split('/')) > 3 
+        simpler = len(path.split('/')) > 3
         simple_path = '/'.join(path.split('/')[3:]) if simpler else path
         return list(lookup_see_also(standard, mapping, simple_path))
 
@@ -106,6 +106,30 @@ def match_codelist(path):
                 pass # FIXME
     return
 
+def is_complete_codelist(codelist_name):
+    """Determine whether the specified Codelist is complete.
+
+    Args:
+        codelist_name (str): The name of the Codelist. This is case-sensitive and must match the mapping file.
+
+    Returns:
+        bool: Whether the Codelist is complete.
+
+    Note:
+        Need to manually specify which Codelists are incomplete - it is not auto-detected. This is due to the surrounding architecture making it a challenge to auto-detect this information.
+
+    """
+    # use a list of incomplete Codelists since it is shorter
+    incomplete_codelists = [
+        'Country',
+        'HumanitarianScopeType',
+        'HumanitarianScopeVocabulary',
+        'IndicatorVocabulary',
+        'OrganisationIdentifier',
+        'OrganisationRegistrationAgency'
+    ]
+    return codelist_name not in incomplete_codelists
+
 def path_to_ref(path):
     return path.replace('//','_').replace('@','.')
 
@@ -117,7 +141,7 @@ def get_extra_docs(rst_filename):
             return fp.read().decode('utf8')
     else:
         return ''
-            
+
 
 
 class Schema2Doc(object):
@@ -137,6 +161,8 @@ def __init__(self, schema, lang):
         self.tree2 = ET.parse("./IATI-Schemas/iati-common.xsd")
         self.jinja_env = jinja2.Environment(loader=jinja2.FileSystemLoader('templates'))
         self.lang = lang
+
+        self.jinja_env.filters['is_complete_codelist'] = is_complete_codelist
 
     def get_schema_element(self, tag_name, name_attribute):
         """
@@ -169,7 +195,7 @@ def output_docs(self, element_name, path, element=None, minOccurs='', maxOccurs=
         element_name.
 
         path is the xpath of the context where this element was found, for the
-        root context, this is the empty string 
+        root context, this is the empty string
 
         """
         if element is None:
@@ -298,7 +324,7 @@ def output_overview_page(self, standard, page, reference_pages):
                 extra_docs=get_extra_docs(os.path.join(self.lang, standard, 'overview', page+'.rst')),
                 reference_pages=reference_pages
             ).encode('utf8'))
-        
+
 
 
     def element_loop(self, element, path):
@@ -340,7 +366,7 @@ def attribute_loop(self, element):
         """
         #if element.find("xsd:complexType[@mixed='true']", namespaces=namespaces) is not None:
         #    print_column_info('text', indent)
-            
+
         a = element.attrib
         type_attributes = []
         type_attributeGroups = []
@@ -359,7 +385,7 @@ def attribute_loop(self, element):
                     )
 
         group_attributes = []
-        for attributeGroup in ( 
+        for attributeGroup in (
             element.findall('xsd:complexType/xsd:attributeGroup', namespaces=namespaces) +
             element.findall('xsd:complexType/xsd:simpleContent/xsd:extension/xsd:attributeGroup', namespaces=namespaces) +
             type_attributeGroups
@@ -397,9 +423,9 @@ def codelists_to_docs(lang):
     for fname in os.listdir(dirname):
         json_file = os.path.join(dirname, fname)
         if not fname.endswith('.json'): continue
-        with open(json_file) as fp: 
+        with open(json_file) as fp:
             codelist_json = json.load(fp)
-        
+
         fname = fname[:-5]
         embedded = os.path.exists(os.path.join('IATI-Codelists','xml',fname+'.xml'))
         if embedded:
@@ -466,7 +492,7 @@ def extra_extra_docs():
             filename='organisation-standard/summary-table.rst',
             title='Organisation Standard Summary Table')
         orgs.output_overview_pages('organisation-standard')
-        
+
         ruleset_page(lang=language)
         codelists_to_docs(lang=language)
     extra_extra_docs()

templates/en/schema_element.rst

@@ -61,10 +61,11 @@ Attributes
   This attribute is required.
 
 {% endif %}{% set codelist_tuple = match_codelist(path+element_name+'/@'+attribute) %}{% if attribute_type %}
+
   This value must be of type {{attribute_type}}.
 
 {% endif %}{% if codelist_tuple[0] %}
-  This value must be on the :doc:`{{codelist_tuple[0]}} codelist </codelists/{{codelist_tuple[0]}}>`{% if codelist_tuple[1] %}, if the relevant vocabulary is used{% endif %}.
+  This value {% if codelist_tuple[0]|is_complete_codelist() %}must{% else %}should{% endif %} be on the :doc:`{{codelist_tuple[0]}} codelist </codelists/{{codelist_tuple[0]}}>`{% if codelist_tuple[1] %}, if the relevant vocabulary is used{% endif %}.
 
 {% endif %}