docs are built in PR/CI and published as artifact if needed (#65)

microsoft · Nov 19, 2020 · c0d1858 · c0d1858
1 parent 2ef40e7
commit c0d1858
Show file tree

Hide file tree

Showing 11 changed files with 100 additions and 1,693 deletions.
diff --git a/.gitignore b/.gitignore
@@ -339,3 +339,6 @@ venv/
 
 # Mkdocs site out
 site/
+
+# Ignore autogenerated C# files
+**/*Autogenerated.cs
diff --git a/README.md b/README.md
@@ -83,7 +83,10 @@ FactoryOrchestrator contains a series of unsigned powershell scripts. Windows se
     Documentation on Execution Policy:
 https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7
 
-When building the source code, keep in mind that certain actions only occur when the build is run as part of an Azure DevOps Pipeline or when run in the "Release" configuration locally. For example, [DocFX documentation](https://dotnet.github.io/docfx/) for the Core and Client Libraries is only generated when the build is run in in one of those two modes. These actions are skipped in Debug builds to increase inner-dev-loop speed.
+## Other notes
+* When building the source code, keep in mind that certain actions only occur when the build is run as part of an Azure DevOps Pipeline or when run in the "Release" configuration locally. For example, [DocFX documentation](https://dotnet.github.io/docfx/) for the Core and Client Libraries is only generated when the build is run in in one of those two modes. These actions are skipped in Debug builds to increase inner-dev-loop speed.
+
+* You may see IntelliSense errors before building FactoryOrchestratorCoreLibrary, as that project creates Autogenerated C# files used in other projects.
 
 ## Debugging
 

diff --git a/build/AutoGenerateInterfaceHelper.ps1 b/build/AutoGenerateInterfaceHelper.ps1
@@ -44,7 +44,7 @@ foreach ($line in $interfaceContent)
                     $summ = $summarySplit[$i];
                     if ($i -eq 1)
                     {
-                        $summ = $summ.Replace("///", "/// Asynchronously");
+                        $summ = $summ.Replace("///", "/// Asynchronously");
                     }
 
                     if ($i -ne $summarySplit.Count - 1)
@@ -55,7 +55,7 @@ foreach ($line in $interfaceContent)
             }
             else
             {
-                $outputContent += $currentSummary
+                $outputContent += $currentSummary
             }
 
             # line is an API in the interface, parse it
@@ -78,8 +78,8 @@ foreach ($line in $interfaceContent)
                 }
                 else
                 {
-                    $outputContent += "async Task<$apiRet> "
-                }
+                    $outputContent += "async Task<$apiRet> "
+                }
             }
             else
             {
@@ -113,7 +113,7 @@ foreach ($line in $interfaceContent)
                 else
                 {
                     $outputContent += "return AsyncClient.$apiName("
-                }
+                }
             }
 
             # Split args, remove default values and variable typesd
@@ -152,7 +152,7 @@ foreach ($line in $interfaceContent)
 
             if ($Async)
             {
-                $outputContent += ")"
+                $outputContent += ")"
             }
             else
             {
@@ -161,9 +161,9 @@ foreach ($line in $interfaceContent)
                     $outputContent += ".Wait()"
                 }
                 else
-                {
-                    $outputContent += ".Result"
-                }
+                {
+                    $outputContent += ".Result"
+                }
             }
 
             $outputContent += ";"
@@ -177,7 +177,7 @@ foreach ($line in $interfaceContent)
             }
             else
             {
-                $outputContent += "`n"
+                $outputContent += "`n"
             }
 
             $outputContent += "$indent$indent}`n`n"
@@ -197,6 +197,12 @@ foreach ($line in $interfaceContent)
 $outputContent += "`n$indent}`n}"
 
 # Save to file
+$OutFolder = [System.IO.Path]::GetDirectoryName($OutputFile)
+if ((Test-Path $OutFolder) -eq $false)
+{
+    $Folder = New-Item -Path $OutFolder -ItemType Directory
+}
+
 Copy-Item -Path "$TemplateFile" -Destination "$OutputFile"
 Add-Content -Path "$OutputFile" -Value "$outputContent"
 

diff --git a/build/azure-pipelines.pr.yml b/build/azure-pipelines.pr.yml
@@ -59,3 +59,27 @@ jobs:
         runInParallel: true
         vsTestVersion: latest
         runSettingsFile: '$(System.DefaultWorkingDirectory)\src\Tests\defaults.runsettings'
+    - script: |
+        cd $(Build.SourcesDirectory)
+        pip install --upgrade pip --upgrade -r $(System.DefaultWorkingDirectory)\docs\requirements.txt
+        mkdocs build --clean --config-file $(System.DefaultWorkingDirectory)\docs\mkdocs.yml
+        git fetch
+        git checkout gh-pages
+        robocopy $(System.DefaultWorkingDirectory)\docs\site\ $(System.DefaultWorkingDirectory)\ /S
+        git restore sitemap.xml*
+        git add -A
+        git diff --cached --exit-code
+        echo ##vso[task.setvariable variable=hasChanges]%errorlevel%
+        mkdir $(Build.ArtifactStagingDirectory)\Patch
+        git diff --cached > $(Build.ArtifactStagingDirectory)\Patch\UpdatedDocs.patch
+      displayName: 'Build and check for changes to website'
+    - task: PublishPipelineArtifact@1
+      displayName: 'Publish patch file as artifact if website has changes'
+      condition: eq(variables['hasChanges'], '1')
+      inputs:
+        artifactName: UpdatedDocsPatch
+        targetPath: $(Build.ArtifactStagingDirectory)\Patch
+    - script: |
+        echo ##vso[task.logissue type=warning]gh-pages documentation needs updating! Use the published UpdatedDocsPatch artifact to update the gh-pages branch after this PR is completed.
+      displayName: 'Warn if website has changes'
+      condition: eq(variables['hasChanges'], '1')
diff --git a/build/azure-pipelines.yml b/build/azure-pipelines.yml
@@ -59,4 +59,27 @@ jobs:
         runInParallel: true
         vsTestVersion: latest
         runSettingsFile: '$(System.DefaultWorkingDirectory)\src\Tests\defaults.runsettings'
-
+    - script: |
+        cd $(Build.SourcesDirectory)
+        pip install --upgrade pip --upgrade -r $(System.DefaultWorkingDirectory)\docs\requirements.txt
+        mkdocs build --clean --config-file $(System.DefaultWorkingDirectory)\docs\mkdocs.yml
+        git fetch
+        git checkout gh-pages
+        robocopy $(System.DefaultWorkingDirectory)\docs\site\ $(System.DefaultWorkingDirectory)\ /S
+        git restore sitemap.xml*
+        git add -A
+        git diff --cached --exit-code
+        echo ##vso[task.setvariable variable=hasChanges]%errorlevel%
+        mkdir $(Build.ArtifactStagingDirectory)\Patch
+        git diff --cached > $(Build.ArtifactStagingDirectory)\Patch\UpdatedDocs.patch
+      displayName: 'Build and check for changes to website'
+    - task: PublishPipelineArtifact@1
+      displayName: 'Publish patch file as artifact if website has changes'
+      condition: eq(variables['hasChanges'], '1')
+      inputs:
+        artifactName: UpdatedDocsPatch
+        targetPath: $(Build.ArtifactStagingDirectory)\Patch
+    - script: |
+        echo ##vso[task.logissue type=warning]gh-pages documentation needs updating! Use the published UpdatedDocsPatch artifact to update the gh-pages branch.
+      displayName: 'Warn if website has changes'
+      condition: eq(variables['hasChanges'], '1')
diff --git a/docs/README.md b/docs/README.md
@@ -4,24 +4,32 @@
 
 We welcome contributions on our documentation as well under the same code of conduct as the rest of the project.
 
-To build & locally view the docs you can follow [these steps](https://www.mkdocs.org/#building-the-site):
+To edit and locally view the docs you can follow [these steps](https://www.mkdocs.org/#building-the-site):
 
-From the root:
+## One-time setup:
 
-1. pip install --upgrade -r requirements.txt
-2. mkdocs build --clean
-3. mkdocs serve
-
-Once you are happy with the changes, you can prepare a pull request to update the checked in docs as you would with any other code change. 
+1. Install python
+2. From this directory (\docs) run: pip install --upgrade -r requirements.txt
 
-When completed, then you will have to manually update the live docs by do the following from the root (todo: make better):
+## Viewing changes locally
+1. From this directory (\docs) run: mkdocs serve
 
-   1. (optional- in case you rev'd it) mkdocs build --clean --config-file .\docs\mkdocs.yml 
-   2. git checkout gh-pages
-   3. git checkout -b <topic branch with>
-   4. Commit your changes, open a pull request. Once approved and the remote 'gh-branch' has the last changes then it will update the website.
+## Commiting changes to the live site
+Once you are happy with your changes, you will have to manually update the live docs by doing the following from the root folder (TODO: make part of the CI build):
 
-## ## Open Source Software Acknowledgments
+   1. Checkout a working branch based on the latest code in 'main'.
+   2. Make your desired documentation changes.
+   3. mkdocs build --clean --config-file .\docs\mkdocs.yml
+   4. git checkout gh-pages
+   5. robocopy /S .\docs\site\ .\
+   6. git checkout -b <your working branch>
+   7. Commit & push your changes, open a pull request into 'gh-pages'. Once approved and the remote 'gh-pages' has the changes it will update the website automatically.
+
+To help prevent documentation<->code mismatches, the GitHub PR build will detect if your code changes will result in any documentation updates. If documentation updates are needed, the build will generate a build warning and publish a Git .patch file. The .patch file can be used to make a PR into 'gh-pages' in lieu of the steps above.
+
+Please note that any changes to the public API surface of the ClientLibrary and/or CoreLibrary classes will result in documentation changes. If you see your changes result in modified files in docs\docs, you must run the above steps to rebuild the website source manually!
+
+## Open Source Software Acknowledgments
 
 ### Mkdocs