Implement documenting default values for rule attributes. (#31)

Issue #2

skydoc/build.proto

@@ -77,19 +77,22 @@ message AttributeDefinition {
 
   // Only present for attributes of type LABEL and LABEL_LIST.
   optional AllowedRuleClassInfo allowed_rule_classes = 4;
-
+  // The documentation for the attribute.
   optional string documentation = 5;
+  // The string representation of the default value of the attribute.
+  optional string default = 6;
 }
 
 message RuleDefinition {
   required string name = 1;
   // Only contains documented attributes
   repeated AttributeDefinition attribute = 2;
-
+  // The documentation for the rule.
   optional string documentation = 3;
-
+  // Documentation illustrating example usages of the rule.
   optional string example_documentation = 4;
 
+  // The list of outputs for this rule.
   repeated OutputTarget output = 5;
 }
 

skydoc/rule.py

@@ -82,7 +82,10 @@ def _get_type_str(self, proto):
         type_str = self.NAME_LINK
       else:
         type_str = 'Unknown'
+
     type_str += '; Required' if proto.mandatory else '; Optional'
+    if proto.HasField('default') and not proto.mandatory:
+      type_str += '; Default is ' + proto.default
     return type_str
 
 

skydoc/rule_extractor.py

@@ -161,9 +161,8 @@ def _assemble_protos(self):
           attr_proto.documentation = attr_desc.doc
         attr_proto.type = attr_desc.type
         attr_proto.mandatory = attr_desc.mandatory
-        # TODO(dzc): Save the default value of the attribute. This will require
-        # adding a proto field to the AttributeDefinition proto, perhaps as a
-        # oneof.
+        if attr_desc.default != None:
+          attr_proto.default = attr_desc.default
 
       for template, doc in rule_desc.output_docs.iteritems():
         output = rule.output.add()

skydoc/rule_extractor_test.py

@@ -47,18 +47,21 @@ def impl(ctx):
         all_types = rule(
             implementation = impl,
             attrs = {
-                "arg_bool": attr.bool(),
-                "arg_int": attr.int(),
-                "arg_int_list": attr.int_list(),
-                "arg_label": attr.label(),
-                "arg_label_list": attr.label_list(),
+                "arg_bool": attr.bool(default=True),
+                "arg_int": attr.int(default=10),
+                "arg_int_list": attr.int_list(default=[1, 2]),
+                "arg_label": attr.label(default=Label("//foo:bar")),
+                "arg_label_list": attr.label_list(
+                    default=[Label("//foo:bar"), Label("//bar:baz")]),
                 "arg_license": attr.license(),
-                "arg_output": attr.output(),
-                "arg_output_list": attr.output_list(),
-                "arg_string": attr.string(),
-                "arg_string_dict": attr.string_dict(),
-                "arg_string_list": attr.string_list(),
-                "arg_string_list_dict": attr.string_list_dict(),
+                "arg_output": attr.output(default=Label("//foo:bar")),
+                "arg_output_list": attr.output_list(
+                    default=[Label("//foo:bar"), Label("//bar:baz")]),
+                "arg_string": attr.string(default="foo"),
+                "arg_string_dict": attr.string_dict(default={"foo": "bar"}),
+                "arg_string_list": attr.string_list(default=["foo", "bar"]),
+                "arg_string_list_dict": attr.string_list_dict(
+                    default={"foo": ["bar", "baz"]}),
             },
         )
         \"\"\"Test rule with all types.
@@ -95,30 +98,35 @@ def impl(ctx):
             type: BOOLEAN
             mandatory: false
             documentation: "A boolean argument."
+            default: "True"
           }
           attribute {
             name: "arg_int"
             type: INTEGER
             mandatory: false
             documentation: "An integer argument."
+            default: "10"
           }
           attribute {
             name: "arg_int_list"
             type: INTEGER_LIST
             mandatory: false
             documentation: "A list of integers argument."
+            default: "[1, 2]"
           }
           attribute {
             name: "arg_label"
             type: LABEL
             mandatory: false
             documentation: "A label argument."
+            default: "//foo:bar"
           }
           attribute {
             name: "arg_label_list"
             type: LABEL_LIST
             mandatory: false
             documentation: "A list of labels argument."
+            default: "[\'//foo:bar\', \'//bar:baz\']"
           }
           attribute {
             name: "arg_license"
@@ -131,36 +139,42 @@ def impl(ctx):
             type: OUTPUT
             mandatory: false
             documentation: "An output argument."
+            default: "//foo:bar"
           }
           attribute {
             name: "arg_output_list"
             type: OUTPUT_LIST
             mandatory: false
             documentation: "A list of outputs argument."
+            default: "[\'//foo:bar\', \'//bar:baz\']"
           }
           attribute {
             name: "arg_string"
             type: STRING
             mandatory: false
             documentation: "A string argument."
+            default: "\'foo\'"
           }
           attribute {
             name: "arg_string_dict"
             type: STRING_DICT
             mandatory: false
             documentation: "A dictionary mapping string to string argument."
+            default: "{\'foo\': \'bar\'}"
           }
           attribute {
             name: "arg_string_list"
             type: STRING_LIST
             mandatory: false
             documentation: "A list of strings argument."
+            default: "[\'foo\', \'bar\']"
           }
           attribute {
             name: "arg_string_list_dict"
             type: STRING_LIST_DICT
             mandatory: false
             documentation: "A dictionary mapping string to list of string argument."
+            default: "{\'foo\': [\'bar\', \'baz\']}"
           }
         }
         """)
@@ -198,6 +212,7 @@ def _impl(ctx):
             name: "arg_string"
             type: STRING
             mandatory: false
+            default: "''"
           }
         }
         """)
@@ -264,6 +279,7 @@ def _public_impl(ctx):
             type: STRING
             mandatory: false
             documentation: "A string argument."
+            default: "''"
           }
         }
         """)
@@ -312,6 +328,7 @@ def _impl(ctx):
             type: BOOLEAN
             mandatory: false
             documentation: "A boolean argument.\\n\\nDocumentation for arg_bool continued here."
+            default: "False"
           }
           attribute {
             name: "arg_label"
@@ -381,6 +398,7 @@ def example_macro(name, foo, visibility=None):
             type: STRING
             mandatory: false
             documentation: "A string argument."
+            default: "''"
           }
         }
         """)
@@ -433,6 +451,7 @@ def _impl(ctx):
             type: STRING
             mandatory: false
             documentation: "A string argument."
+            default: "''"
           }
         }
         """)
@@ -491,6 +510,7 @@ def _impl(ctx):
             type: STRING
             mandatory: false
             documentation: "A string argument."
+            default: "''"
           }
           output {
             template: "%{name}_deploy.jar"

skydoc/stubs/attr.py

@@ -81,15 +81,16 @@ def compare_priority(self):
 
 def bool(default=False, mandatory=False):
   return AttrDescriptor(
-      build_pb2.Attribute.BOOLEAN, default=default, mandatory=mandatory)
+      build_pb2.Attribute.BOOLEAN, default=repr(default), mandatory=mandatory)
 
 
 def int(default=0, mandatory=False, values=[]):
-  return AttrDescriptor(build_pb2.Attribute.INTEGER, default, mandatory)
+  return AttrDescriptor(build_pb2.Attribute.INTEGER, repr(default), mandatory)
 
 
 def int_list(default=[], mandatory=False, non_empty=False, allow_empty=True):
-  return AttrDescriptor(build_pb2.Attribute.INTEGER_LIST, default, mandatory)
+  return AttrDescriptor(build_pb2.Attribute.INTEGER_LIST, repr(default),
+                        mandatory)
 
 
 def label(default=None,
@@ -102,6 +103,8 @@ def label(default=None,
           single_file=False,
           cfg=None,
           aspects=[]):
+  if default != None:
+    default = repr(default)
   return AttrDescriptor(build_pb2.Attribute.LABEL, default, mandatory)
 
 
@@ -115,36 +118,50 @@ def label_list(default=[],
                allow_empty=True,
                cfg=None,
                aspects=[]):
-  return AttrDescriptor(build_pb2.Attribute.LABEL_LIST, default, mandatory)
+  default_val = []
+  for label in default:
+    default_val.append(repr(label))
+  return AttrDescriptor(build_pb2.Attribute.LABEL_LIST, repr(default_val),
+                        mandatory)
 
 
 def license(default=None, mandatory=False):
+  if default != None:
+    default = repr(default)
   return AttrDescriptor(build_pb2.Attribute.LICENSE, default, mandatory)
 
 
 def output(default=None, mandatory=False):
+  if default != None:
+    default = repr(default)
   return AttrDescriptor(build_pb2.Attribute.OUTPUT, default, mandatory)
 
 
 def output_list(default=[], mandatory=False, non_empty=False, allow_empty=True):
-  return AttrDescriptor(build_pb2.Attribute.OUTPUT_LIST, default, mandatory)
+  default_val = []
+  for label in default:
+    default_val.append(repr(label))
+  return AttrDescriptor(build_pb2.Attribute.OUTPUT_LIST, repr(default_val),
+                        mandatory)
 
 
 def string(default="", mandatory=False, values=[]):
-  return AttrDescriptor(build_pb2.Attribute.STRING, default, mandatory)
+  return AttrDescriptor(build_pb2.Attribute.STRING, repr(default), mandatory)
 
 
 def string_dict(default={}, mandatory=False, non_empty=False, allow_empty=True):
-  return AttrDescriptor(build_pb2.Attribute.STRING_DICT, default, mandatory)
+  return AttrDescriptor(build_pb2.Attribute.STRING_DICT, repr(default),
+                        mandatory)
 
 
 def string_list(default=[], mandatory=False, non_empty=False, allow_empty=True):
-  return AttrDescriptor(build_pb2.Attribute.STRING_LIST, default, mandatory)
+  return AttrDescriptor(build_pb2.Attribute.STRING_LIST, repr(default),
+                        mandatory)
 
 
 def string_list_dict(default={},
                      mandatory=False,
                      non_empty=False,
                      allow_empty=True):
-  return AttrDescriptor(build_pb2.Attribute.STRING_LIST_DICT, default,
+  return AttrDescriptor(build_pb2.Attribute.STRING_LIST_DICT, repr(default),
                         mandatory)

skydoc/stubs/skylark_globals.py

@@ -49,6 +49,9 @@ class Label(object):
   def __init__(self, label_string):
     self.label_string = label_string
 
+  def __repr__(self):
+    return self.label_string
+
 class RuleDescriptor(object):
   def __init__(self, implementation, test=False, attrs={}, outputs={},
                executable=False, output_to_genfiles=False, fragments=[],