Ansible Markdown Parser

.ci/containers/go-ruby-python/Dockerfile

@@ -1,4 +1,4 @@
-FROM gcr.io/magic-modules/go-ruby:1.11.5-2.6.0-v2
+FROM gcr.io/magic-modules/go-ruby:1.11.5-2.6.0-v3
 
 # Install python & python libraries.
 RUN apt-get update

.ci/containers/go-ruby/Gemfile

@@ -3,6 +3,7 @@ source 'https://rubygems.org'
 gem 'activesupport'
 gem 'binding_of_caller'
 gem 'rake'
+gem 'redcarpet'
 
 group :test do
   gem 'erb_lint'

.ci/containers/go-ruby/Gemfile.lock

@@ -71,6 +71,7 @@ GEM
       loofah (~> 2.2, >= 2.2.2)
     rainbow (3.0.0)
     rake (12.3.1)
+    redcarpet (3.4.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -113,6 +114,7 @@ DEPENDENCIES
   octokit
   parallel_tests
   rake
+  redcarpet
   rspec
   rubocop (~> 0.63.1)
 

.ci/magic-modules/generate-ansible.yml

@@ -8,7 +8,7 @@ image_resource:
     type: docker-image
     source:
         repository: gcr.io/magic-modules/go-ruby-python
-        tag: '1.11.5-2.6.0-2.7-v2'
+        tag: '1.11.5-2.6.0-2.7-v3'
 
 inputs:
     - name: magic-modules-branched

.ci/magic-modules/generate-inspec.yml

@@ -8,7 +8,7 @@ image_resource:
     type: docker-image
     source:
         repository: gcr.io/magic-modules/go-ruby-python
-        tag: '1.11.5-2.6.0-2.7-v2'
+        tag: '1.11.5-2.6.0-2.7-v3'
 
 inputs:
     - name: magic-modules-branched

.ci/magic-modules/generate-terraform.yml

@@ -8,7 +8,7 @@ image_resource:
     type: docker-image
     source:
         repository: gcr.io/magic-modules/go-ruby-python
-        tag: '1.11.5-2.6.0-2.7-v2'
+        tag: '1.11.5-2.6.0-2.7-v3'
 
 inputs:
     - name: magic-modules-branched

Gemfile

@@ -3,6 +3,7 @@ source 'https://rubygems.org'
 gem 'activesupport'
 gem 'binding_of_caller'
 gem 'rake'
+gem 'redcarpet'
 
 group :test do
   gem 'erb_lint'

Gemfile.lock

@@ -71,6 +71,7 @@ GEM
       loofah (~> 2.2, >= 2.2.2)
     rainbow (3.0.0)
     rake (12.3.1)
+    redcarpet (3.4.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -113,6 +114,7 @@ DEPENDENCIES
   octokit
   parallel_tests
   rake
+  redcarpet
   rspec
   rubocop (~> 0.63.1)
 

provider/ansible/documentation.rb

@@ -14,21 +14,23 @@
 require 'compile/core'
 require 'provider/config'
 require 'provider/core'
+require 'provider/ansible/markdown'
 
 # Rubocop doesn't like this file because the hashes are complicated.
 # Humans like this file because the hashes are explicit and easy to read.
 module Provider
   module Ansible
     # Responsible for building out YAML documentation blocks.
     module Documentation
+      include Provider::Ansible::Markdown
       # Builds out the DOCUMENTATION for a property.
       # This will eventually be converted to YAML
       def documentation_for_property(prop)
         required = prop.required && !prop.default_value ? true : false
         {
           prop.name.underscore => {
             'description' => [
-              format_description(prop.description),
+              description(prop.description),
               (resourceref_description(prop) \
                if prop.is_a?(Api::Type::ResourceRef) && !prop.resource_ref.readonly),
               (choices_description(prop) \
@@ -68,7 +70,7 @@ def returns_for_property(prop)
                             && prop.item_type.is_a?(Api::Type::NestedObject))
         {
           prop.name => {
-            'description' => format_description(prop.description),
+            'description' => description(prop.description),
             'returned' => 'success',
             'type' => type,
             'contains' => (
@@ -102,15 +104,6 @@ def choices_description(prop)
         "Some valid choices include: #{prop.values.map { |x| "\"#{x}\"" }.join(', ')}"
       end
 
-      # MM puts descriptions in a text block. Ansible needs it in bullets
-      def format_description(desc)
-        desc.split(".\n").map do |paragraph|
-          paragraph += '.' unless paragraph.end_with?('.')
-          paragraph = format_url(paragraph)
-          paragraph.tr("\n", ' ').strip.squeeze(' ')
-        end
-      end
-
       # Find URLs and surround with U()
       # If there's a period at the end of the URL, make sure the
       # period is outside of the ()

provider/ansible/markdown.rb

@@ -0,0 +1,99 @@
+# Copyright 2017 Google Inc.
+# 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.
+
+require 'compile/core'
+require 'provider/config'
+require 'provider/core'
+require 'redcarpet'
+
+module Provider
+  module Ansible
+    # Responsible for building out YAML documentation
+    # from Markdown
+    # This is primarily done for parsing descriptions.
+    module Markdown
+      DELIMITER = '$$$'.freeze
+
+      def description(text)
+        # Description texts should have leading + trailing spaces
+        # removed so that they are not mistaken for code blocks by the
+        # Markdown parser.
+        Redcarpet::Markdown.new(AnsibleDescriptionRender)
+                           .render(text.strip.squeeze("\n"))
+                           .split(DELIMITER)
+                           .map(&:strip)
+      end
+
+      # This is a rendering class that takes in
+      # a Markdown description and returns an
+      # array of strings. This is used exclusively for
+      # description documentation.
+      #
+      # Redcarpet will return a String (because that's the expectation of markdown).
+      # Ansible wants an array of strings, so this class will return a single string
+      # with the '$$$' character denoting where the string should be split.
+      class AnsibleDescriptionRender < Redcarpet::Render::Base
+        LIST_DELIMITER = '%%%'.freeze
+        # Returns a paragraph with delimiters showing where it should be split.
+        def paragraph(text)
+          text.split(".\n").map do |paragraph|
+            paragraph += '.' unless paragraph.end_with?('.')
+            paragraph = format_url(paragraph)
+            paragraph.tr("\n", ' ').squeeze(' ')
+          end.join(DELIMITER)
+        end
+
+        def codespan(code)
+          "\"#{code}\""
+        end
+
+        def normal_text(text)
+          text
+        end
+
+        def link(link, _title, content)
+          if content
+            "L(#{content},#{link})"
+          else
+            "U(#{link})"
+          end
+        end
+
+        def list(content, _list_type)
+          content.split(LIST_DELIMITER).join(', ')
+        end
+
+        # List items come first. We have to place special delimiters
+        # because all of the list strings are joined together before
+        # list() is called.
+        def list_item(text, _list_type)
+          "#{text.sub("\n", '')}#{LIST_DELIMITER}"
+        end
+
+        private
+
+        # Find URLs and surround with U()
+        # If there's a period at the end of the URL, make sure the
+        # period is outside of the ()
+        def format_url(paragraph)
+          paragraph.gsub(%r{
+            https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]
+            [a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+
+            [a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))
+            [a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9]\.[^\s]{2,}
+          }x, 'U(\\0)').gsub('.)', ').')
+        end
+      end
+    end
+  end
+end

templates/ansible/documentation.erb

@@ -14,7 +14,7 @@ DOCUMENTATION = '''
 ---
 <%= to_yaml({
   'module' => module_name(object),
-  'description' => format_description(object.description),
+  'description' => description(object.description),
   'short_description' => "Creates a GCP #{object.name}",
   'version_added' => version_added(object).to_f,
   'author' => "Google Inc. (@googlecloudplatform)",

templates/ansible/facts.erb

@@ -34,7 +34,7 @@ DOCUMENTATION = '''
   'options' => [
     ({
       object.facts.filter.name.underscore => {
-        'description' => format_description(object.facts.filter.description)
+        'description' => description(object.facts.filter.description)
       }
     } if object.facts.has_filters),
     uri_props.map { |p| documentation_for_property(p) }