Improve the parameter checking and logging in the WIKIPDF exporter (#…

…1577)

Fixes #1573
* Updates parameter checking
* Update documentation

Extensions/WikiPDFExport/WikiPDFExportTask/src/ExportFunctions.ts

@@ -72,20 +72,28 @@ export async function ExportPDF(
                 logError(`Cannot find wiki folder ${wikiRootPath}`);
                 return;
             } else {
+                logInfo(`Using ${wikiRootPath} as the root path to export`);
                 args += ` -p "${wikiRootPath}"`;
             }
         }
 
         if (singleFile.length > 0) {
-            if (!fs.existsSync(`${singleFile}`)) {
+            // first check for a fully specified path
+            if (fs.existsSync(`${singleFile}`)) {
+                logInfo(`Found file the file ${singleFile} relative to the current working directory`);
+                args += ` -s "${singleFile}"`;
+            } else if (fs.existsSync(`${path.join(wikiRootPath, singleFile)}`)) {
+                logInfo(`Found file using the expanded relative path of ${path.join(wikiRootPath, singleFile)}`);
+                args += ` -s "${singleFile}"`; // we don't to add the wikiRootPath as it is already included in the -p parameter
+            } else {
                 logError(`Cannot find the requested file ${singleFile} to export`);
                 return;
-            } else {
-                args += ` -s "${singleFile}"`;
             }
         } else {
-            if (!fs.existsSync(`${wikiRootPath}/.order`)) {
-                logInfo(`No filename specified and cannot find the .order file in the root of the wiki, the exported PDF will therefore be empty`);
+            if (!fs.existsSync(`${path.join(wikiRootPath, ".order")}`)) {
+                logWarning(`No filename specified and cannot find the .order file in the root of the wiki, the exported PDF will therefore be empty. Consider setting the underlying AzureDevOps.WikiPDFExport tools property '--include-unlisted-pages' using the 'ExtraParameters' parameter`);
+            } else {
+                logInfo(`Using the .order file in the root of the wiki to determine the order of the pages to export`);
             }
         }
 

Extensions/WikiPDFExport/WikiPDFExportTask/task/task.json

@@ -62,7 +62,7 @@
       "label": "Single file to export",
       "defaultValue": "",
       "required": false,
-      "helpMarkDown": "Name of the single file to be exported, default is empty i.e. whole repo is exported e.g. myfile.md"
+      "helpMarkDown": "Single file to export. Can be set as either a relative path to a file in the `localPath` or `RootExportPath` folder e.g. page.md or as fully specified path. If not set the whole WIKI is exported based on the structure details the `.order` file in the root of the repo"
     },
     {
       "name": "useAgentToken",
@@ -105,7 +105,7 @@
       "label": "Local folder",
       "defaultValue": "",
       "required": false,
-      "helpMarkDown": "The path to the root of the cloned the repo if exporting the whole repo, a folder within the repo to export part of the repo or finally the folder containing a single file to export. For this final option the filename must be specified below"
+      "helpMarkDown": "If not set, this defaults to the path of the root of the cloned the repo. It can be set to a folder within the cloned repo export only part of the repo. If only a single file is required the a filename can be specified using the singleFile parameter"
     },
     {
       "name": "outputFile",

Extensions/WikiPDFExport/readme.md

@@ -7,7 +7,7 @@ When run, the task will download the current release (or optionally a pre-releas
    - Optionally clone a Git based WIKI repo that is hosted on Azure DevOps or GitHub into a local folder for exporting
    - Or if you already have the folder structure on the agent then this feature can be skipped
 2. The task will then export either
-   - the whole WIKI structure as a PDF (based on the .order file is present in the root)
+   - the whole WIKI structure as a PDF (based on the .order file which must be present in the repo root)
    - a single named file
 
 ## How the AzureDevOps.WikiPDFExport tool is obtained
@@ -60,8 +60,8 @@ steps:
 
 ## Parameters
 ### AzureDevOps.WikiPDFExport Specific
-- SingleFile - Optional single file to export in the localPath folder e.g. page.md
-- RootExportPath - The path to the root of the cloned the repo if exporting the whole repo, a folder within the repo to export part of the repo or finally the folder containing a single file to export. For this final option the filename must be specified below
+- SingleFile - Single file to export. Can be set as either a relative path to a file in the `localPath` or `RootExportPath` folder e.g. page.md or as fully specified path. If not set the whole WIKI is exported based on the structure details the `.order` file in the root of the repo.
+- RootExportPath - Optional: If not set, this defaults to the path of the root of the cloned the repo. It can be set to a folder within the cloned repo export only part of the repo. If only a single file is required the a filename can be specified using the `singleFile`` parameter
 - ExtraParameters - Any optional extra as defined at [WikiPDFExport](https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport/) you wish to pass to the command line tool - noting that this task automatically manages the -p, -s, -c and -v parameters
 - usePreRelease - If set to true pre-release version of the [AzureDevOps.WikiPDFExport tool](https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport) tool will be used
 - overrideExePath - An optional path to a previously download copy of the [AzureDevOps.WikiPDFExport tool](https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport). If not set the task will download the current release of this tool

Extensions/WikiPDFExport/test-stage.yml

@@ -49,6 +49,15 @@ steps:
     singleFile: 'inline.md'
     outputFile: '$(Build.ArtifactStagingDirectory)/PDF/$(Agent.OS)-singleFile.pdf'
     downloadPath: '${{parameters.localpath}}'
+- task: richardfennellBM.BM-VSTS-WikiPDFExport-Tasks-DEV.WikiPDFExportTask.WikiPdfExportTask@3
+  displayName: 'Export Single File'
+  inputs:
+    cloneRepo: false
+    usePreRelease: false
+    localpath: '$(System.DefaultWorkingDirectory)'
+    singleFile: 'inline.md'
+    outputFile: '$(Build.ArtifactStagingDirectory)/PDF/$(Agent.OS)-singleFile.pdf'
+    downloadPath: '${{parameters.localpath}}'
 - task: richardfennellBM.BM-VSTS-WikiPDFExport-Tasks-DEV.WikiPDFExportTask.WikiPdfExportTask@3
   displayName: 'Export Public GitHub WIKI'
   condition: succeededOrFailed()
@@ -79,6 +88,18 @@ steps:
     localpath: '$(System.DefaultWorkingDirectory)/repopartial'
     rootExportPath: '$(System.DefaultWorkingDirectory)/repopartial/folder'
     downloadPath: '${{parameters.localpath}}'
+- task: richardfennellBM.BM-VSTS-WikiPDFExport-Tasks-DEV.WikiPDFExportTask.WikiPdfExportTask@3
+  displayName: 'Export single part of the Azure DevOps WIKI'
+  condition: succeededOrFailed()
+  inputs:
+    cloneRepo: true
+    repo: 'https://dev.azure.com/richardfennell/GitHub/_git/GitHub.wiki'
+    useAgentToken: true
+    outputFile: '$(Build.ArtifactStagingDirectory)/PDF/$(Agent.OS)-AzrepoFilterSingle.pdf'
+    localpath: '$(System.DefaultWorkingDirectory)/repopartial1'
+    rootExportPath: '$(System.DefaultWorkingDirectory)/repopartial1/folder'
+    downloadPath: '${{parameters.localpath}}'
+    singlefile: 'test1.md'
 - task: richardfennellBM.BM-VSTS-WikiPDFExport-Tasks-DEV.WikiPDFExportTask.WikiPdfExportTask@3
   displayName: 'Export Azure DevOps WIKI without downloading tool'
   condition: and(succeededOrFailed(), eq(variables['AGENT.OS'], 'Windows_NT'))