Generate html documentation for enterprise policies

Use the .json and .grd description of the policies to generate HTML markup that can be uploaded straight to dev.chromium.org. BUG=54712 TEST=DocWriterUnittest.* Review URL: http://codereview.chromium.org/3452006 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@60032 0039d316-1c4b-4281-b951-d872f2087c98
FairyWorld · Sep 21, 2010 · 4c4c45b · 4c4c45b
1 parent 4b2b8ca
commit 4c4c45b
Show file tree

Hide file tree

Showing 11 changed files with 1,007 additions and 32 deletions.
diff --git a/chrome/app/policy/policy_templates.grd b/chrome/app/policy/policy_templates.grd
@@ -8,6 +8,8 @@ templates and will be translated for each locale. -->
   <outputs>
     <output filename="app/policy/windows/admx/chrome.admx" type="admx" lang="en" />
     <output filename="app/policy/windows/admx/en-US/chrome.adml" type="adml" lang="en" />
+    <output filename="app/policy/common/html/policy_list.html" type="doc" lang="en" />
+
     <output filename="app/policy/windows/adm/am/chrome.adm" type="adm" lang="am" />
     <output filename="app/policy/windows/adm/ar/chrome.adm" type="adm" lang="ar" />
     <output filename="app/policy/windows/adm/bg/chrome.adm" type="adm" lang="bg" />
@@ -522,6 +524,74 @@ templates and will be translated for each locale. -->
     </message>
     <!-- End Chrome Frame messages -->
 
+    <!-- Generated documentation messages -->
+    <message name="IDS_POLICY_DOC_DATA_TYPE"
+             desc="Caption text of the field 'data type' in the summary chart of a policy in the generated documentation">
+      Data type:
+    </message>
+    <message name="IDS_POLICY_DOC_WIN_REG_LOC"
+             desc="Caption text of the field 'windows registry location' in the summary chart of a policy in the generated documentation">
+      Windows registry location:
+    </message>
+    <message name="IDS_POLICY_DOC_MAC_LINUX_PREF_NAME"
+             desc="Caption text of the field 'mac/linux preference name' in the summary chart of a policy in the generated documentation">
+      Mac/Linux preference name:
+    </message>
+    <message name="IDS_POLICY_DOC_SUPPORTED_ON_PLATFORMS"
+             desc="Caption text of the list of 'platforms where this policy is supported' in the summary chart of a policy in the generated documentation">
+      Supported on platforms:
+    </message>
+    <message name="IDS_POLICY_DOC_SUPPORTED_IN_PRODUCTS"
+             desc="Caption text of the list of 'products where this policy is supported' in the summary chart of a policy in the generated documentation">
+      Supported in products:
+    </message>
+    <message name="IDS_POLICY_DOC_SUPPORTED_FEATURES"
+             desc="Caption text of the list of 'policy features that this policy supports' in the summary chart of a policy in the generated documentation">
+      Supported features:
+    </message>
+    <message name="IDS_POLICY_DOC_DESCRIPTION"
+             desc="Caption text of the 'description text' in the summary chart of a policy in the generated documentation">
+      Description:
+    </message>
+    <message name="IDS_POLICY_DOC_EXAMPLE_VALUE"
+             desc="Caption text of the field 'example value' in the summary chart of a policy in the generated documentation">
+      Example value:
+    </message>
+    <message name="IDS_POLICY_DOC_INTRO"
+             desc="Introduction text for the generated policy documentation">
+      This is the list of policies that Chromium respects.
+
+      You don't need to change these settings by hand!  You can download easy-to-use templates from
+      <ph name="POLICY_TEMPLATE_DOWNLOAD_URL">$5<ex>
+        http://www.chromium.org/administrators/policy-templates</ex></ph>.
+    </message>
+    <message name="IDS_POLICY_DOC_NOTE"
+             desc="Warning notice for policies in the generated policy documentation">
+      NOTE: there are some issues about this policy, visit
+      <ph name="POLICY_TEMPLATE_DOWNLOAD_URL">$6<ex>
+        http://www.chromium.org/administrators/policy-list-3/serious-problem</ex></ph> for more details.
+    </message>
+    <message name="IDS_POLICY_DOC_BACK_TO_TOP"
+             desc="Text of a link in the generated policy documentation, that takes the user to the top of the page">
+      Back to top
+    </message>
+    <message name="IDS_POLICY_DOC_SUPPORTED"
+             desc="Appears next to the name of each supported feature in the 'list of supported policy features' in the generated policy documentation">
+      Yes
+    </message>
+    <message name="IDS_POLICY_DOC_NOT_SUPPORTED"
+             desc="Appears next to the name of each unsupported feature in the 'list of supported policy features' in the generated policy documentation">
+      No
+    </message>
+    <message name="IDS_POLICY_DOC_NAME_COLUMN_TITLE"
+             desc="Appears at the top of the policy summary table, over the column of policy names, in the generated policy documentation">
+      Policy Name
+    </message>
+    <message name="IDS_POLICY_DOC_DESCRIPTION_COLUMN_TITLE"
+             desc="Appears at the top of the policy summary table, over the column of short policy descriptions, in the generated policy documentation">
+      Description
+    </message>
+    <!-- End of generated documentation messages  -->
     </messages>
   </release>
 </grit>
diff --git a/chrome/app/policy/policy_templates.json b/chrome/app/policy/policy_templates.json
@@ -22,14 +22,15 @@
 #   'string' - a string value
 #   'enum' - the user can select its value from a collection of items
 #   'main' - a boolean value with additional semantics:
-#     A group can have at most one main policy and it must have a value of true
-#     if the policy group is enabled, false if the group is disabled or no
-#     value if the policy is not specified. Chrome will see this policy no
-#     differently than other policies, but depending on the platform, the GUI
-#     of the templates might reflect the fact that these policies are 'main'.
-#     For example on Windows this policy will be assigned to the Enable/Disable
-#     buttons of the group, and if it is set to Disabled then other policies of
-#     the group will not be visible to Chrome.
+#     A group can have at most one main policy and it must have a value of True
+#     if the policy group is enabled, False if the group is disabled and not
+#     configured (not visible to Chrome at all) if the rest of the group is
+#     not configured. Chrome will see this policy no differently than other
+#     policies, but depending on the platform, the GUI of the templates might
+#     reflect the fact that these policies are 'main'. For example on Windows
+#     this policy will be assigned to the Enable/Disable buttons of the group,
+#     and if it is set to Disabled then other policies of the group will not be
+#     visible to Chrome.
 #   'list' - a list of string values
 #
 # Policy group descriptions, policy captions and similar texts are localized
@@ -94,6 +95,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': 'http://chromium.org',
         }
       }],
     },
@@ -106,6 +108,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': True,
         }
       }],
     },
@@ -118,7 +121,8 @@
           'platforms': ['win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 0},
-        }
+          'example_value': 'en',
+        },
       }]
     },
     {
@@ -128,8 +132,10 @@
         'type': 'main',
         'annotations': {
           'platforms': ['linux', 'mac', 'win'],
+          'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
-        }
+          'example_value': True,
+        },
       }]
     },
     {
@@ -141,6 +147,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': True,
         }
       }],
     },
@@ -153,6 +160,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 0},
+          'example_value': True,
         }
       }],
     },
@@ -165,6 +173,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 0},
+          'example_value': True,
         }
       }]
     },
@@ -177,6 +186,10 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 0},
+          'example_value': True,
+          'problem_href':
+            'http://www.chromium.org/administrators/'
+            'policy-list-3/metrics-reporting-enabled',
         }
       }],
     },
@@ -189,6 +202,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': True,
         }
       }]
     },
@@ -201,6 +215,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': False,
         }
       }]
     },
@@ -213,6 +228,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': False,
         }
       }]
     },
@@ -225,6 +241,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': ['Java', 'Shockwave Flash', 'Chrome PDF Viewer'],
         }
       }]
     },
@@ -237,6 +254,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': True,
         }
       }]
     },
@@ -256,6 +274,7 @@
             'platforms': ['linux', 'mac', 'win'],
             'products': ['chrome'],
             'features': {'dynamic_refresh': 0},
+            'example_value': 2,
           }
         },
         {
@@ -265,6 +284,7 @@
             'platforms': ['linux', 'mac', 'win'],
             'products': ['chrome'],
             'features': {'dynamic_refresh': 0},
+            'example_value': '123.123.123.123:8080',
           }
         },
         {
@@ -274,6 +294,7 @@
             'platforms': ['linux', 'mac', 'win'],
             'products': ['chrome'],
             'features': {'dynamic_refresh': 0},
+            'example_value': 'http://internal.site/example.pac'
           }
         },
         {
@@ -283,6 +304,7 @@
             'platforms': ['linux', 'mac', 'win'],
             'products': ['chrome'],
             'features': {'dynamic_refresh': 0},
+            'example_value': 'http://www.example1.com,http://www.example2.com,http://internalsite/',
           }
         },
       ]
@@ -296,6 +318,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': ['extension_id1', 'extension_id2']
         }
       }]
     },
@@ -308,6 +331,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': ['extension_id1', 'extension_id2']
         }
       }]
     },
@@ -320,6 +344,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': True
         }
       }]
     },
@@ -337,6 +362,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': 4,
         }
       },{
         'name': 'RestoreOnStartupURLs',
@@ -345,6 +371,7 @@
           'platforms': ['linux', 'mac', 'win'],
           'products': ['chrome'],
           'features': {'dynamic_refresh': 1},
+          'example_value': ['http://example.com', 'http://chromium.org'],
         }
       }]
     },
@@ -361,6 +388,7 @@
           'platforms': ['win'],
           'products': ['chrome_frame'],
           'features': {'dynamic_refresh': 0},
+          'example_value': 1,
         }
       }, {
         'name': 'RenderInChromeFrameList',
@@ -369,6 +397,7 @@
           'platforms': ['win'],
           'products': ['chrome_frame'],
           'features': {'dynamic_refresh': 0},
+          'example_value': ['http://www.example.com', 'http://www.example.edu'],
         }
       }, {
         'name': 'RenderInHostList',
@@ -377,12 +406,14 @@
           'platforms': ['win'],
           'products': ['chrome_frame'],
           'features': {'dynamic_refresh': 0},
+          'example_value': ['http://www.example.com', 'http://www.example.edu'],
         }
       }],
     },
   ],
   'placeholders': [
     # Note: keys $1 and $3 are reserved for Chromium and Chromium Frame.
+    # Key $6 is reserved for doc_writer.
     {
       'key': '$2',
       'value': 'http://www.chromium.org/developers/design-documents/network-settings#TOC-Command-line-options-for-proxy-sett'
@@ -391,5 +422,9 @@
       'key': '$4',
       'value': 'http://www.chromium.org/developers/how-tos/chrome-frame-getting-started'
     },
+    {
+      'key': '$5',
+      'value': 'http://www.chromium.org/administrators/policy-templates'
+    },
   ]
 }
diff --git a/tools/grit/grit/format/policy_templates/policy_template_generator.py b/tools/grit/grit/format/policy_templates/policy_template_generator.py
@@ -107,7 +107,12 @@ def _AddMessagesToPolicies(self):
       if 'policies' in group:
         # Iterate through all the policies in the current group.
         for policy in group['policies']:
+          # Add messages to the policy.
           self._AddMessagesToPolicy(policy)
+          # Store a reference to the group of the policy. This makes
+          # it easier to look up messages of the group when we have
+          # a policy, like in PListStringsWriter and DocWriter.
+          policy['parent'] = group
 
   def _GetPoliciesForWriter(self, template_writer, group):
     '''Filters the list of policies in a group for a writer.

diff --git a/tools/grit/grit/format/policy_templates/writers/adml_writer.py b/tools/grit/grit/format/policy_templates/writers/adml_writer.py
@@ -29,10 +29,6 @@ class ADMLWriter(xml_formatted_writer.XMLFormattedWriter):
   # describe the presentation of Policy-Groups and Policies.
   _presentation_table_elem = None
 
-  # The active Policy-Group. At any given point in time this contains the
-  # Policy-Group that is processed.
-  _active_policy_group = None
-
   # The active ADML "presentation" element. At any given point in time this
   # contains the "presentation" element for the Policy-Group that is processed.
   _active_presentation_elem = None
@@ -200,8 +196,6 @@ def BeginPolicyGroup(self, group):
     Args:
       group: The Policy-Group to generate ADML elements for.
     '''
-    self._active_policy_group = group
-
     # Add ADML "string" elements to the string-table that are required by a
     # Policy-Group.
     id = group['name']