Include Documentation to UPM package

Unity Package Manager expects the offline documentation
at "Documentation~/index.md". This change makes sure
it is generated through export script.

Change-Id: I00af261c3610880b3a90e0bd90598f3f61968b13

Author: chkuang-g

export_unity_package_config.json

@@ -53,6 +53,7 @@
       "readme": "ExternalDependencyManager/Editor/README.md",
       "license": "ExternalDependencyManager/Editor/LICENSE",
       "changelog": "ExternalDependencyManager/Editor/CHANGELOG.md",
+      "documentation": "ExternalDependencyManager/Editor/README.md",
 
       "common_manifest" : {
         "name": "com.google.external-dependency-manager",

source/ExportUnityPackage/export_unity_package.py

@@ -537,6 +537,10 @@
 # Valid version for asset package in form of major.minor.patch(-preview)
 VALID_VERSION_RE = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(-preview)?$")
 
+# Documentation folder and filename for UPM package.
+UPM_DOCUMENTATION_DIRECTORY = "Documentation~"
+UPM_DOCUMENTATION_FILENAME = "index.md"
+
 # String and unicode classes used to check types with safe_dict_get_value()
 try:
   unicode("")  # See whether unicode class is available (Python < 3)
@@ -1008,20 +1012,28 @@ def get_guid(self, path):
 
 
 def copy_and_set_rwx(source_path, target_path):
-  """Copy a file and set the target file to readable / writeable & executable.
+  """Copy a file/folder and set the target to readable / writeable & executable.
 
   Args:
     source_path: File to copy from.
     target_path: Path to copy to.
   """
   logging.debug("Copying %s --> %s", source_path, target_path)
-  target_dir = os.path.dirname(target_path)
-  if not os.path.exists(target_dir):
-    os.makedirs(target_dir)
-  shutil.copy(source_path, target_path)
-  os.chmod(target_path, (stat.S_IRWXU | stat.S_IRWXG | stat.S_IROTH |
-                         stat.S_IXOTH))
-
+  file_mode = stat.S_IRWXU | stat.S_IRWXG | stat.S_IROTH | stat.S_IXOTH
+
+  if os.path.isfile(source_path):
+    target_dir = os.path.dirname(target_path)
+    if not os.path.exists(target_dir):
+      os.makedirs(target_dir)
+    shutil.copy(source_path, target_path)
+    os.chmod(target_path, file_mode)
+  elif os.path.isdir(source_path):
+    shutil.copytree(source_path, target_path)
+    for current_dir, directories, filenames in os.walk(target_path):
+      for directory in [os.path.join(current_dir, d) for d in directories]:
+        os.chmod(directory, file_mode)
+      for filename in [os.path.join(current_dir, f) for f in filenames]:
+        os.chmod(filename, file_mode)
 
 def version_handler_tag(islabel=True, field=None, value=None):
   """Generate a VersionHandler filename or label.
@@ -2720,6 +2732,44 @@ def write_upm(self,
             timestamp)
         logging.info("- Processed %s --> %s", asset.filename, asset_file)
 
+      # Copy documents to "Documentation~" folder.
+      # See https://docs.unity3d.com/Manual/cus-layout.html
+      # All folders and files does not need meta file or the link on Unity
+      # Package Manager would fail.
+      source_doc = safe_dict_get_value(self._json, "documentation")
+      if source_doc:
+        # Try to find the source doc from assets directory
+        for assets_dir in assets_dirs:
+          source_doc_candidate = os.path.join(assets_dir, source_doc)
+          if os.path.exists(source_doc_candidate):
+            source_doc = source_doc_candidate
+        if os.path.isfile(source_doc):
+          # Copy file
+          target_doc = os.path.join(staging_dir, "package",
+                                    UPM_DOCUMENTATION_DIRECTORY,
+                                    UPM_DOCUMENTATION_FILENAME)
+          logging.info("- Copying doc file %s --> %s", source_doc, target_doc)
+          copy_and_set_rwx(source_doc, target_doc)
+        elif os.path.isdir(source_doc):
+          target_doc_dir = os.path.join(staging_dir, "package",
+                                        UPM_DOCUMENTATION_DIRECTORY)
+          # Check if index.md exists
+          if not os.path.exists(os.path.join(source_doc,
+                                             UPM_DOCUMENTATION_FILENAME)):
+            raise ProjectConfigurationError(
+                "Cannot find index.md under '%s' for package '%s'. Perhaps it "
+                "is not included in assets_dir or assets_zip?" % (
+                    source_doc, self.name))
+
+          logging.info("- Copying doc folder %s --> %s",
+                       source_doc, target_doc_dir)
+          copy_and_set_rwx(source_doc, target_doc_dir)
+        else:
+          raise ProjectConfigurationError(
+              "Cannot find documentation at '%s' for package '%s'. Perhaps the "
+              "file/folder is not included in assets_dir or assets_zip?" % (
+                  from_location, self.name))
+
       # Create the .tgz file.
       PackageConfiguration.create_archive(unity_package_file, staging_dir,
                                           timestamp)

source/ExportUnityPackage/export_unity_package_test.py

@@ -2988,6 +2988,7 @@ def test_package_write_upm(self):
                 }],
                 "manifest_path": "PlayServicesResolver/Editor",
                 "readme": "PlayServicesResolver/Editor/README.md",
+                "documentation": "PlayServicesResolver/Doc",
                 "includes":
                     ["ios-resolver.unitypackage", "jar-resolver.unitypackage"],
                 "common_manifest": {
@@ -3069,6 +3070,8 @@ def test_package_write_upm(self):
           "Google.VersionHandlerImpl_v1.2.87.0.dll",
           "package/PlayServicesResolver/Editor/"
           "Google.VersionHandlerImpl_v1.2.87.0.dll.meta",
+          "package/Documentation~",
+          "package/Documentation~/index.md",
       ], unitypackage_file.getnames())
       unitypackage_file.extractall(self.staging_dir)
 
@@ -3081,6 +3084,14 @@ def test_package_write_upm(self):
                   self.staging_dir, "package/PlayServicesResolver/Editor/"
                   "Google.VersionHandler.dll")))
 
+      self.assertTrue(
+          filecmp.cmp(
+              os.path.join(
+                  self.assets_dir,
+                  "PlayServicesResolver/Doc/index.md"),
+              os.path.join(
+                  self.staging_dir, "package/Documentation~/index.md")))
+
       # Check package.json
       with open(os.path.join(self.staging_dir, "package/package.json"),
                 "rt") as manifest:
@@ -3110,6 +3121,76 @@ def test_package_write_upm(self):
         self.assertEqual(expected_override_metadata,
                          yaml_dict["PluginImporter"]["platformData"])
 
+  def test_package_write_upm_documentation_as_file(self):
+    """Test write_upm() with documentation path as a file."""
+    project = export_unity_package.ProjectConfiguration(
+        {
+            "packages": [{
+                "name": "play-services-resolver.unitypackage",
+                "imports": [{
+                    "paths": [
+                        "PlayServicesResolver/Editor/Google.VersionHandler.dll",
+                    ]
+                }],
+                "manifest_path": "PlayServicesResolver/Editor",
+                # Use README.md as documentation.
+                "documentation": "PlayServicesResolver/Editor/README.md",
+                "common_manifest": {
+                    "name": "com.google.play-services-resolver",
+                },
+                "export_upm": 1
+            }]
+        }, set(), "1.0.0")
+    package = project.packages_by_name["play-services-resolver.unitypackage"]
+
+    upm_package = package.write_upm(
+        export_unity_package.GuidDatabase(
+            export_unity_package.DuplicateGuidsChecker(), {
+                "1.0.0": {
+                    "PlayServicesResolver/Editor/README.md":
+                        "baa27a4c0385454899a759d9852966b7",
+                    "PlayServicesResolver/Editor/"
+                    "play-services-resolver_version-1.0.0_manifest.txt":
+                        "353f6aace2cd42adb1343fc6a808f62e",
+                    "com.google.play-services-resolver/package.json":
+                        "782a38c5f19e4bb99e927976c8daa9ac",
+                    "com.google.play-services-resolver/PlayServicesResolver":
+                        "fa7daf703ad1430dad0cd8b764e5e6d2",
+                    "com.google.play-services-resolver/PlayServicesResolver/"
+                    "Editor":
+                        "2334cd7684164851a8a53db5bd5923ca",
+                }
+            }, "1.0.0"), [self.assets_dir], self.staging_dir, 0)
+
+    with tarfile.open(upm_package, "r:gz") as upm_package_file:
+      # Check included files.
+      self.assertCountEqual([
+          "package",
+          "package/package.json",
+          "package/package.json.meta",
+          "package/PlayServicesResolver",
+          "package/PlayServicesResolver.meta",
+          "package/PlayServicesResolver/Editor",
+          "package/PlayServicesResolver/Editor.meta",
+          "package/PlayServicesResolver/Editor/Google.VersionHandler.dll",
+          "package/PlayServicesResolver/Editor/Google.VersionHandler.dll.meta",
+          "package/PlayServicesResolver/Editor/"
+          "play-services-resolver_version-1.0.0_manifest.txt",
+          "package/PlayServicesResolver/Editor/"
+          "play-services-resolver_version-1.0.0_manifest.txt.meta",
+          "package/Documentation~",
+          "package/Documentation~/index.md",
+      ], upm_package_file.getnames())
+      upm_package_file.extractall(self.staging_dir)
+
+      self.assertTrue(
+          filecmp.cmp(
+              os.path.join(
+                  self.assets_dir,
+                  "PlayServicesResolver/Editor/README.md"),
+              os.path.join(
+                  self.staging_dir, "package/Documentation~/index.md")))
+
   def test_package_write_upm_missing_readme(self):
     """Test write_upm() with misconfigured readme path."""
     project = export_unity_package.ProjectConfiguration(
@@ -3204,13 +3285,20 @@ def setUp(self):
     """Unpack resources to a temporary directory."""
     super(FileOperationsTest, self).setUp()
     self.assets_dir = os.path.join(TEST_DATA_PATH, "Assets")
+    self.temp_dir = os.path.join(FLAGS.test_tmpdir, "copy_temp")
+    os.makedirs(self.temp_dir)
+
+  def tearDown(self):
+    """Clean up the temporary directory."""
+    super(FileOperationsTest, self).tearDown()
+    shutil.rmtree(self.temp_dir)
 
   def test_copy_and_set_rwx(self):
     """Copy a file and set it to readable / writeable and executable."""
     source_path = os.path.join(
         self.assets_dir,
         "PlayServicesResolver/Editor/play-services-resolver_v1.2.87.0.txt")
-    target_path = os.path.join(FLAGS.test_tmpdir,
+    target_path = os.path.join(self.temp_dir,
                                "play-services-resolver_v1.2.87.0.txt")
     self.assertFalse(os.path.exists(target_path))
 
@@ -3227,7 +3315,7 @@ def test_copy_and_set_rwx_new_dir(self):
         self.assets_dir,
         "PlayServicesResolver/Editor/play-services-resolver_v1.2.87.0.txt")
     target_path = os.path.join(
-        FLAGS.test_tmpdir,
+        self.temp_dir,
         "a/nonexistent/directory/play-services-resolver_v1.2.87.0.txt")
     self.assertFalse(os.path.exists(target_path))
 
@@ -3262,6 +3350,29 @@ def test_copy_files_to_dir(self):
     finally:
       export_unity_package.copy_and_set_rwx = original_copy_and_set_rwx
 
+  def test_copy_dir_to_dir(self):
+    """Test copying directory into a directory recursively."""
+    source_path = os.path.join(
+        self.assets_dir,
+        "PlayServicesResolver")
+    target_path = os.path.join(
+        FLAGS.test_tmpdir,
+        "a/nonexistent/directory")
+    self.assertFalse(os.path.exists(target_path))
+
+    export_unity_package.copy_and_set_rwx(source_path, target_path)
+    self.assertTrue(os.path.exists(target_path))
+    cmp_result = filecmp.dircmp(source_path, target_path)
+    self.assertFalse(cmp_result.left_only or cmp_result.right_only or
+                     cmp_result.diff_files)
+    self.assertEqual(
+        stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR,
+        os.stat(os.path.join(target_path, "Editor")).st_mode & stat.S_IRWXU)
+    self.assertEqual(
+        stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR,
+        (os.stat(os.path.join(target_path, "Editor.meta")).st_mode &
+            stat.S_IRWXU))
+
 
 class ReadJsonFileTest(absltest.TestCase):
   """Test reading a JSON file."""

source/ExportUnityPackage/test_data/Assets/PlayServicesResolver/Doc/index.md

@@ -0,0 +1 @@
+A documentation file