Add docs.microsoft.com artifact generation (#576)

* Add version.txt
* Add doc generation for template
* Add version.hpp parsing and update capabilities to cmake and engsys
* Get-SdkVersion -> Get-PkgVersion
* Move Update-PkgVersion.ps1 under eng/scripts
* Get-PackageVersion -> Get-PkgVersion
* Update paths, params, verbosity
* Couple fixes to output and make use of new SemVer version
* Add fallback support for verison.txt in cases where we still use it to unblock release artifact generation
* Use version information in release pipeline
* Add workaround to generate storage pipeline artifacts
* eng/scripts/
* Write warning
* Haven't released storage-file-shares yet according to releases on GitHub
* Set release date on changelog.md
* Update CHANGELOG.md to indicate this is a test release
* Add docs.microsoft.com artifact generation
* Add arguments
* newline
* d->s
* publish docs.ms artifact
* Consolidate archetype-sdk-client.yml docs.ms generation steps
* publish not the docs.ms for we publish it as part of packages
* Better folder structure

cmake-modules/doxygen_common.cmake

@@ -21,6 +21,7 @@ function(generate_documentation PROJECT_NAME PROJECT_VERSION)
         set(DOXYGEN_HTML_FOOTER ${CMAKE_SOURCE_DIR}/eng/docs/api/assets/footer.html)
         set(DOXYGEN_HTML_STYLESHEET ${CMAKE_SOURCE_DIR}/eng/docs/api/assets/style.css)
 
+        set(DOXYGEN_GENERATE_XML YES)
         set(DOXYGEN_GENERATE_LATEX NO)
         # Use MathJax instead of latex to render formulas
         set(DOXYGEN_USE_MATHJAX YES)

eng/pipelines/templates/jobs/archetype-sdk-client.yml

@@ -120,6 +120,9 @@ jobs:
             -DBUILD_CURL_TRANSPORT=OFF
             -DBUILD_DOCUMENTATION=YES
 
+      - pwsh: npm install -g moxygen
+        displayName: Install Moxygen to generate markdown for docs.microsoft.com
+
       # Generate package spec JSON files for tagging the repo
       - ${{ each artifact in parameters.Artifacts }}:
           - pwsh: >-
@@ -156,7 +159,20 @@ jobs:
             workingDirectory: build
             displayName: Generate docs (${{ artifact.Name }}-docs)
 
-          - pwsh: New-Item -ItemType directory -Path $(Build.ArtifactStagingDirectory) -Name docs/${{ artifact.Name }}
+          - task: PowerShell@2
+            inputs:
+              targetType: filePath
+              filePath: eng/scripts/New-DocsMsArtifact.ps1
+              arguments: >-
+                -ServiceDirectory ${{ parameters.ServiceDirectory }}
+                -PackageName ${{ artifact.Name }}
+                -TargetFolder $(Build.ArtifactStagingDirectory)/packages/${{ artifact.Name }}/docs/docs.ms
+              ignoreLASTEXITCODE: true
+              pwsh: true
+            displayName: Generate artifacts for docs.ms
+
+          - pwsh: |
+              New-Item -ItemType directory -Path $(Build.ArtifactStagingDirectory) -Name docs/${{ artifact.Name }}
             displayName: Create doc artifact location
 
           - task: CopyFiles@2
@@ -177,7 +193,7 @@ jobs:
           artifactName: packages
           path: $(Build.ArtifactStagingDirectory)/packages
 
-      # After all docs artifacts are generated publis docs artifacts
+      # After all docs artifacts are generated publish docs artifacts
       - task: PublishPipelineArtifact@1
         inputs:
           artifactName: docs

eng/scripts/New-DocsMsArtifact.ps1

@@ -0,0 +1,16 @@
+[CmdletBinding()]
+Param (
+    [ValidateNotNullOrEmpty()]
+    [string] $RepoRoot = "${PSScriptRoot}/../..",
+    [Parameter(Mandatory=$True)]
+    [string] $ServiceDirectory,
+    [Parameter(Mandatory=$True)]
+    [string] $PackageName,
+    [string] $TargetFolder = "$RepoRoot/build/sdk/$ServiceDirectory/$PackageName/docs/docs.ms"
+)
+
+npm install -g moxygen
+
+$docsPath = "$RepoRoot/build/sdk/$ServiceDirectory/$PackageName/docs"
+New-Item -ItemType directory -Path $TargetFolder -Force
+moxygen --anchors --output "$TargetFolder/api-docs.md" "$docsPath/xml"