[[ Docs ]] Support Edition element in lcdoc

montegoulding · montegoulding · commit cf864c3c6889 · 2017-09-06T14:16:33.000+10:00
This patch implements support for the `Edition` element in lcdoc
files. The `Edition` element:

- should have a value that corresponds to a LiveCode edition
- is inherited and overridable when declared in a library document

This patch also implements support for documentation to be read
from component folders that declare their edition in a YAML metadata
file.
diff --git a/builder/builder_utilities.livecodescript b/builder/builder_utilities.livecodescript
@@ -323,8 +323,9 @@ function builderMergExtVersion
    return kMergExtVersion
 end builderMergExtVersion
 
-function builderUnpackFolder
-   return sWorkDir & "/ext/unpacked"
+function builderUnpackFolder pEdition
+   replace space with "_" in pEdition
+   return sWorkDir & "/ext/unpacked/" & toLower(pEdition)
 end builderUnpackFolder
 
 function builderTSNetVersion
@@ -595,7 +596,7 @@ end builderMergExtDownloadedFilePath
 
 private command builderMergExtUnpack pMergExtVersion, pEdition
    local tFolder
-   put builderUnpackFolder() & slash & "Ext" into tFolder
+   put builderUnpackFolder(pEdition) & slash & "Ext" into tFolder
    
    local tZipFile
    put builderMergExtDownloadedFilePath(pMergExtVersion, pEdition) into tZipFile
@@ -620,7 +621,7 @@ end builderTSNetDownloadedFilePath
 
 private command builderTSNetUnpack pTSNetVersion, pEdition
    local tFolder
-   put builderUnpackFolder() & slash & "Ext" into tFolder
+   put builderUnpackFolder(pEdition) & slash & "Ext" into tFolder
    
    local tZipFile
    put builderTSNetDownloadedFilePath(pTSNetVersion, pEdition) into tZipFile
@@ -637,7 +638,7 @@ end builderTSNetUnpack
 
 command builderExtUnpack pEdition
    local tFolder
-   put builderUnpackFolder() & slash & "Ext" into tFolder
+   put builderUnpackFolder(pEdition) & slash & "Ext" into tFolder
    
    if there is a folder tFolder then
       builderLog "message", "Cleaning unpack folder" && tFolder
@@ -678,7 +679,7 @@ An commma delimited list
 
 **/
 function builderEditionNames
-   return "Business,Indy,Community Extra,Community"
+   return "Business,Indy,Community+,Community"
 end builderEditionNames
 
 /**
diff --git a/builder/docs_builder.livecodescript b/builder/docs_builder.livecodescript
@@ -1913,7 +1913,7 @@ end escape
 command docsBuilderGenerateDocsNew pEdition, pVersion   
    start using stack (builderRepoFolder() & slash & "ide-support" & slash & "revdocsparser.livecodescript")
    
-   builderExtUnpack pEdition
+   builderExtUnpack "Business"
    
    builderLog "report", "Building guide into" && builderGuideFolder(pEdition) & slash & "distributed_guide.js"
    pathEnsure (builderGuideFolder(pEdition))
@@ -1946,14 +1946,6 @@ private command addFolderToListIfExists pFolder, pThrowIfNot, @xArray
    end if
 end addFolderToListIfExists
 
-private function RepoEditionDocsFolder pEdition
-   if editionIsInPrivateRepo(pEdition) then
-      return builderPrivateRepoFolder() & slash & "docs" & slash & toLower(pEdition)
-   else
-      return builderRepoFolder() & slash & "docs" & slash & toLower(pEdition)
-   end if
-end RepoEditionDocsFolder
-
 private command docsBuilderGetGuideFolders pEdition, @xFolders
    local tRepoGuides
    put builderRepoFolder() & slash & "docs" & slash & "guides" into tRepoGuides
@@ -1963,49 +1955,31 @@ private command docsBuilderGetGuideFolders pEdition, @xFolders
    put builderIDEDocsFolder() & slash & "guides" into tIDEGuides
    addFolderToListIfExists tIDEGuides, true, xFolders
    
-   repeat for each item tEdition in "indy,business"
-      if editionCompare(pEdition, tEdition) >= 0 then
-         local tGuides
-         put RepoEditionDocsFolder(tEdition) & slash & "guides" into tGuides
-         addFolderToListIfExists tGuides, false, xFolders
+   local tComponents
+   put builderComponentFolders() into tComponents
+   
+   repeat for each element tComponent in tComponents
+      if editionCompare(pEdition, tComponent["metadata"]["edition"]) >= 0 then
+         addFolderToListIfExists tComponent["folder"] & slash & "guides", false, xFolders
       end if
    end repeat
-
+   
    addFolderToListIfExists builderBuiltGuidesFolder(), false, xFolders
 end docsBuilderGetGuideFolders
 
 private command docsBuilderAddExtFolders pEdition, @xFolders
-   local tDefaultFolder
-   put the defaultFolder into tDefaultFolder
-   
    local tTargetFolder
-   put builderUnpackFolder() & slash & "Ext" into tTargetFolder
-   set the defaultFolder to tTargetFolder
-   
-   repeat for each line tFolder in the folders
+   put builderUnpackFolder("Business") & slash & "Ext" into tTargetFolder
+   repeat for each line tFolder in folders(tTargetFolder)
       if tFolder is ".." then next repeat
       addFolderToListIfExists tTargetFolder & slash & tFolder, true, xFolders
    end repeat
-   
-   set the defaultFolder to tDefaultFolder
 end docsBuilderAddExtFolders
 
 private command docsBuilderGetAdditionalFolders pEdition, @xFolders
    docsBuilderAddExtFolders pEdition, xFolders
 end docsBuilderGetAdditionalFolders
 
-private command docsBuilderGetDictionaryFolders pEdition, @xFolders
-   local tCommunityDocs
-   put builderRepoFolder() & slash & "docs" into tCommunityDocs
-   addFolderToListIfExists tCommunityDocs, true, xFolders
-   
-   repeat for each item tEdition in "indy,business"
-      if editionCompare(pEdition, tEdition) >= 0 then
-         addFolderToListIfExists RepoEditionDocsFolder(), true, xFolders
-      end if
-   end repeat
-end docsBuilderGetDictionaryFolders
-
 command docsBuilderGenerateDistributedGuide pEdition
    local tGuideFoldersA
    docsBuilderGetGuideFolders pEdition, tGuideFoldersA
@@ -2048,26 +2022,22 @@ end docsFileGetUTF8Contents
 
 -- Find all lcdoc files in pFolder and add them to the list of docs 
 -- data in xLibraryA
-private command addToDictionaryFromFolder pFolder, @xLibraryA
-   local tDefaultFolder
-   put the defaultFolder into tDefaultFolder
-   
+private command addToDictionaryFromFolder pFolder, pDefaults, @xLibraryA
    docsBuilderProgressUpdate "", "Building dictionary from folder" && pFolder
-   set the defaultfolder to pFolder
-   get the files
+   
+   get files(pFolder)
    filter it with "*.lcdoc"
    repeat for each line tFile in it
       local tText, tParsedA
       wait 0 with messages
       put docsFileGetUTF8Contents(pFolder & slash & tFile, true) into tText
-      put revDocsParseDocText(tText) into tParsedA
+      put revDocsParseDocText(tText, pFolder & slash & tFile, pDefaults) into tParsedA
       repeat for each element tDoc in tParsedA["doc"]
          -- TODO: Work out why something empty is returned
          if tDoc["display name"] is empty then next repeat
          addToList tDoc, xLibraryA
       end repeat
    end repeat
-   set the defaultFolder to tDefaultFolder
 end addToDictionaryFromFolder
 
 /*
@@ -2077,40 +2047,39 @@ pRootDirs (array): An array of paths to the relevant root folders of the
 dictionary.
 */
 
-command docsBuilderParseDictionaryToLibraryArray pRootDirs, @xDocsA
-   local tDefaultFolder
-   put the defaultFolder into tDefaultFolder
-   
-   # Get the list of canonical glossary entries
-   local tGlossaryA
-   repeat for each element tRootDir in pRootDirs
-      union tGlossaryA with revDocsCollectGlossarySynonyms(tRootDir)
-   end repeat
-   
-   repeat for each element tRootDir in pRootDirs      
+command docsBuilderParseDictionaryToLibraryArray pComponents, @xDocsA
+   repeat for each element tComponent in pComponents      
       local tDictionaryRoot, tGlossaryRoot
-      put tRootDir & slash & "dictionary" into tDictionaryRoot
-      put tRootDir & slash & "glossary" into tGlossaryRoot
+      put tComponent["folder"] & slash & "dictionary" into tDictionaryRoot
+      put tComponent["folder"] & slash & "glossary" into tGlossaryRoot
+      
+      local tDefaults
+      delete variable tDefaults
+      if tComponent["metadata"]["edition"] is not empty then
+         put editionDisplayName(tComponent["metadata"]["edition"]) into tDefaults["edition"]
+      end if
       
       repeat for each item tRoot in (tDictionaryRoot & "," & tGlossaryRoot)
-         set the defaultfolder to tRoot
-         repeat for each line tLine in the folders
+         if there is not a folder tRoot then
+            next repeat
+         end if
+         
+         repeat for each line tLine in folders(tRoot)
             if tLine is ".." then next repeat
-            addToDictionaryFromFolder tRoot & slash & tLine, xDocsA
+            addToDictionaryFromFolder tRoot & slash & tLine, tDefaults, xDocsA
          end repeat
       end repeat
    end repeat
-   set the defaultFolder to tDefaultFolder
 end docsBuilderParseDictionaryToLibraryArray
 
 command docsBuilderParseAdditionalFoldersToLibraryArray pDirs, @xDocsA
    local tFolder
    repeat for each element tFolder in pDirs      
-      addToDictionaryFromFolder tFolder, xDocsA
+      addToDictionaryFromFolder tFolder, empty, xDocsA
    end repeat
 end docsBuilderParseAdditionalFoldersToLibraryArray
 
-function docsBuilderParseDictionary pLibraryName, pAuthor, pRootDirsA, pAdditionalDirsA, pRecursive
+function docsBuilderParseDictionary pLibraryName, pAuthor, pComponents, pAdditionalDirsA, pRecursive
    local tLibraryA
    
    put revDocsModifyForUrl(pLibraryName) into tLibraryA["name"]
@@ -2119,7 +2088,7 @@ function docsBuilderParseDictionary pLibraryName, pAuthor, pRootDirsA, pAddition
    put "dictionary" into tLibraryA["type"]
    
    -- Special case for the dictionary / glossary data extraction
-   docsBuilderParseDictionaryToLibraryArray pRootDirsA, tLibraryA["doc"]
+   docsBuilderParseDictionaryToLibraryArray pComponents, tLibraryA["doc"]
    
    -- Add any additional docs to the dictionary
    docsBuilderParseAdditionalFoldersToLibraryArray pAdditionalDirsA, tLibraryA["doc"]
@@ -2132,14 +2101,23 @@ function docsBuilderParseDictionary pLibraryName, pAuthor, pRootDirsA, pAddition
 end docsBuilderParseDictionary
 
 command docsBuilderGenerateDistributedAPI pEdition
-   local tDictionaryFolders, tAdditionalFolders
-   docsBuilderGetDictionaryFolders pEdition, tDictionaryFolders
+   local tAdditionalFolders
    docsBuilderGetAdditionalFolders pEdition, tAdditionalFolders
    
    local tLibrariesA
    
+   local tComponents
+   put builderComponentFolders() into tComponents
+   
+   -- special case the main docs folder
+   local tIndex
+   put the number of elements of tComponents + 1 into tIndex
+   put builderRepoFolder() & "/docs" into tComponents[tIndex]["folder"]
+   put "engine" into tComponents[tIndex]["metadata"]["category"]
+   put "community" into tComponents[tIndex]["metadata"]["edition"]
+   
    local tLCSDictionaryA
-   put docsBuilderParseDictionary("LiveCode Script", "LiveCode", tDictionaryFolders, tAdditionalFolders, false) into tLCSDictionaryA
+   put docsBuilderParseDictionary("LiveCode Script", "LiveCode", tComponents, tAdditionalFolders, false) into tLCSDictionaryA
    
    if tLCSDictionaryA is empty then
       logError "Couldn't parse script dictionary data for" && pEdition
diff --git a/builder/release_notes_builder.livecodescript b/builder/release_notes_builder.livecodescript
@@ -70,7 +70,7 @@ command releaseNotesBuilderRun pEdition, pVersion, pReleaseType, pOutputDir
                put "extension" into tComponents[tIndex]["metadata"]["category"]
                
                if tPath is  builderPrivateRepoFolder() then
-                  put "community extra" into tComponents[tIndex]["metadata"]["edition"]
+                  put "community+" into tComponents[tIndex]["metadata"]["edition"]
                else
                   put "community" into tComponents[tIndex]["metadata"]["edition"]
                end if
diff --git a/builder/tools_builder.livecodescript b/builder/tools_builder.livecodescript
@@ -130,7 +130,7 @@ private command toolsBuilderPrepareExt pEdition, pPlatform
    -- Remove un-needed files from the unpacked Ext collection
    local tOldFolder
    local tCollectionFolder
-   put builderUnpackFolder() & slash & "Ext" into tCollectionFolder
+   put builderUnpackFolder(pEdition) & slash & "Ext" into tCollectionFolder
    put the defaultFolder into tOldFolder
    set the defaultFolder to tCollectionFolder
    repeat for each line tExtension in the folders
@@ -198,7 +198,7 @@ private command toolsBuilderMakePackage pVersion, pEdition, pPlatform, pEngineFo
    packageCompilerConfigureSOurce tPackager, "emscripten", pEngineFolders["emscripten"]
    packageCompilerConfigureSource tPackager, "prebuilt", builderRepoFolder() & slash & "prebuilt"
    packageCompilerConfigureSource tPackager, "repo", builderRepoFolder()
-   packageCompilerConfigureSource tPackager, "ext", builderUnpackFolder()
+   packageCompilerConfigureSource tPackager, "ext", builderUnpackFolder(pEdition)
    if editionIsInPrivateRepo(tEditionType) then
       packageCompilerConfigureSource tPackager, "private", builderPrivateRepoFolder()
    end if
diff --git a/ide-support/revdocsparser.livecodescript b/ide-support/revdocsparser.livecodescript
