validator_gen_md.py

#
# Copyright 2015 The AMP HTML Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS-IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the license.
#
"""Generates validator-generated.md"""

import os


def GenerateValidatorGeneratedMd(specfile, validator_pb2, text_format, out):
  """Main method for the markdown generator.

  This method reads the specfile and emits Markdown to sys.stdout.

  Args:
    specfile: Path to validator.protoascii.
    validator_pb2: The proto2 Python module generated from validator.proto.
    text_format: The text_format module from the protobuf package, e.g.
        google.protobuf.text_format.
    out: a list of lines to output (without the newline characters), to
        which this function will append.
  """
  out.append('<!-- Generated by %s - do not edit. -->' %
             os.path.basename(__file__))
  out.append(
      '<!-- WARNING: This does not fully reflect validator.protoascii yet. -->')
  out.append('')
  out.append('[Accelerated Mobile Pages Project](https://www.ampproject.org)')
  out.append('')

  out.append('# validator.protoascii')
  out.append('')

  rules = validator_pb2.ValidatorRules()
  text_format.Merge(open(specfile).read(), rules)
  if rules.HasField('spec_file_revision'):
    out.append('* spec file revision: %d' % rules.spec_file_revision)
  if rules.HasField('min_validator_revision_required'):
    out.append('* minimum validator revision required: %d' %
               rules.min_validator_revision_required)
  out.append('')
  out.append('Allowed Tags')
  out.append('')
  out.append('[TOC]')
  out.append('')
  for (field_desc, field_val) in rules.ListFields():
    if field_desc.name == 'tags':
      for tag_spec in field_val:
        PrintTagSpec(validator_pb2, tag_spec, out)


def GetLayout(validator_pb2, layout_index):
  """Helper function that returns the AmpLayout.Layout name for a given index.

  See amp.validator.AmpLayout.Layout in validator.proto for details.

  Args:
    validator_pb2: The proto2 Python module generated from validator.proto.
    layout_index: integer representing a particular AmpLayout.Layout
  Returns:
    A string which represents the name for this supported layout.
  """
  amp_layout = validator_pb2.DESCRIPTOR.message_types_by_name['AmpLayout']
  layouts = amp_layout.fields_by_name['supported_layouts'].enum_type.values
  return layouts[layout_index].name


def PrintAmpLayout(validator_pb2, amp_layout, out):
  """Prints a Markdown version of the given proto message (AmpLayout).

  See amp.validator.AmpLayout in validator.proto for details of proto message.

  Args:
    validator_pb2: The proto2 Python module generated from validator.proto.
    amp_layout: The AmpLayout message.
    out: A list of lines to output (without newline characters), to which this
         function will append.
  """
  for layout in amp_layout.supported_layouts:
    out.append('* %s' % UnicodeEscape(GetLayout(validator_pb2, layout)))
  if amp_layout.defines_default_width:
    out.append('* Defines Default Width')
  if amp_layout.defines_default_height:
    out.append('* Defines Default Height')


def PrintAttrSpec(attr_spec, out):
  """Prints a Markdown version of the given proto message (AttrSpec).

  See amp.validator.AttrSpec in validator.proto for details of proto message.

  Args:
    attr_spec: The AttrSpec message.
    out: A list of lines to output (without newline characters), to which this
         function will append.
  """
  out.append('* %s' % UnicodeEscape(attr_spec.name))
  if attr_spec.alternative_names:
    out.append('    * Alternative Names: %s' %
               RepeatedFieldToString(attr_spec.alternative_names))
  if attr_spec.mandatory:
    out.append('    * Mandatory')
  if attr_spec.mandatory_oneof:
    out.append('    * Mandatory One of: %s' % attr_spec.mandatory_oneof)
  if attr_spec.value:
    out.append('    * Required Value: %s' % attr_spec.value)


def PrintTagSpec(validator_pb2, tag_spec, out):
  """Prints a Markdown version of the given proto message (TagSpec).

  See amp.validator.TagSpec in validator.proto for details of proto message.

  Args:
    validator_pb2: The proto2 Python module generated from validator.proto.
    tag_spec: The TagSpec message.
    out: A list of lines to output (without newline characters), to which this
         function will append.
  """
  header = '## %s' % UnicodeEscape(tag_spec.tag_name)
  if tag_spec.spec_name and (tag_spec.tag_name != tag_spec.spec_name):
    header += ': %s' % UnicodeEscape(tag_spec.spec_name)
  if tag_spec.deprecation:
    header += ' (DEPRECATED)'
  header += '{#%s_%s}' % (UnicodeEscape(tag_spec.tag_name).replace(' ', '_'),
                          UnicodeEscape(tag_spec.spec_name).replace(' ', '_'))
  out.append('')
  out.append(header)
  out.append('')
  if tag_spec.deprecation:
    out.append('This is deprecated.')
    out.append('Please see [%s](%s)' %
               (UnicodeEscape(tag_spec.deprecation), tag_spec.deprecation_url))
    out.append('')
  if tag_spec.mandatory:
    out.append('* Mandatory')
  if tag_spec.mandatory_alternatives:
    out.append('* Mandatory Alternatives: %s' %
               UnicodeEscape(tag_spec.mandatory_alternatives))
  if tag_spec.unique:
    out.append('* Unique')
  if tag_spec.mandatory_parent:
    out.append('* Mandatory Parent: %s' %
               UnicodeEscape(tag_spec.mandatory_parent))
  if tag_spec.mandatory_ancestor:
    out.append('* Mandatory Ancestor: %s' %
               UnicodeEscape(tag_spec.mandatory_ancestor))
  if tag_spec.mandatory_ancestor_suggested_alternative:
    out.append('* Mandatory Ancestor Alternative: %s' %
               UnicodeEscape(tag_spec.mandatory_ancestor_suggested_alternative))
  if tag_spec.disallowed_ancestor:
    out.append('* Disallowed Ancestor: %s' %
               RepeatedFieldToString(tag_spec.disallowed_ancestor))
  if tag_spec.also_requires_tag:
    out.append('* Also Requires: %s' %
               RepeatedFieldToString(tag_spec.also_requires_tag))
  if tag_spec.attrs:
    out.append('')
    out.append('Allowed Attributes:')
    out.append('')
    for attr_spec in tag_spec.attrs:
      PrintAttrSpec(attr_spec, out)
  if (tag_spec.amp_layout.supported_layouts or
      tag_spec.amp_layout.defines_default_width or
      tag_spec.amp_layout.defines_default_height):
    out.append('')
    out.append('Allowed Layouts:')
    out.append('')
    PrintAmpLayout(validator_pb2, tag_spec.amp_layout, out)
  if tag_spec.spec_url:
    out.append('')
    out.append('[Spec](%s)' % tag_spec.spec_url)
    out.append('')


def RepeatedFieldToString(field):
  """Helper function which converts a list into an escaped string.

  Args:
    field: A list of strings.
  Returns:
    A string, segmented by commas.
  """
  return ', '.join([UnicodeEscape(s) for s in field])


def UnderscoreToTitleCase(under_score):
  """Helper function which converts under_score names to TitleCase.

  Args:
    under_score: A name, segmented by under_scores.
  Returns:
    A name, segmented as TitleCase.
  """
  segments = under_score.split('_')
  return ' '.join([s.title() for s in segments])


def UnicodeEscape(string):
  """Helper function which escapes unicode characters.

  Args:
    string: A string which may contain unicode characters.
  Returns:
    An escaped string.
  """
  return ('' + string).encode('unicode-escape')