Automatically publish API docs (#364)

* Added PublishDocs.ps1

* Added documentation branch index

* Added version info to doxygen

* Added pipeline step to publish docs

* Added automated identity

* Added build trigger for feature branches

* Added API documentation link to README.md

* Added mainpage.md to doxygen output

CMakeLists.txt

@@ -106,13 +106,15 @@ add_subdirectory(tools)
 if (K4A_BUILD_DOCS)
     find_package(Doxygen 1.8.14 EXACT)
     if (DOXYGEN_FOUND)
+        set(DOXYGEN_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/doxygen/mainpage.md) 
         set(DOXYGEN_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/include/k4a ${CMAKE_CURRENT_SOURCE_DIR}/include/k4arecord ${DOXYGEN_MAINPAGE})
-        set(DOXYGEN_LAYOUT_FILE ${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml)
+        set(DOXYGEN_LAYOUT_FILE ${CMAKE_CURRENT_SOURCE_DIR}/doxygen/DoxygenLayout.xml)
         # These variables are used in Doxyfile.in
         string(REPLACE ";" " " DOXYGEN_INPUT "${DOXYGEN_SOURCES}")
         set(DOXYGEN_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/docs)
         set(DOXYGEN_PROJECT_LOGO ${CMAKE_CURRENT_SOURCE_DIR}/docs/logo.png)
         set(DOXYGEN_TEMPLATE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/doxygen)
+        set(DOXYGEN_PROJECT_NUMBER ${SOURCE_BRANCH})
 
         configure_file(doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 

README.md

@@ -35,7 +35,7 @@ The latest stable binaries are available for download.
 ---------|----------------
   [v1.0.2](https://github.com/Microsoft/Azure-Kinect-Sensor-SDK/releases/tag/v1.0.2) | [Azure Kinect SDK 1.0.2.msi](http://download.microsoft.com/download/B/4/D/B4D26442-DDA5-40C2-9913-3B23AE84A806/Azure%20Kinect%20SDK%201.0.2.msi)
 
-Please see [usage](docs/usage.md) for info on how to use the SDK.
+Please see [usage](docs/usage.md) for info on how to use the SDK. [API documentation](https://microsoft.github.io/Azure-Kinect-Sensor-SDK/) is also available.
 
 ## Building
 

azure-pipelines.yml

@@ -19,6 +19,7 @@ trigger:
     - develop
     - release/*
     - hotfix/*
+    - feature/*
 
 jobs:
 - job: WindowsK4ABuildTest
@@ -437,7 +438,7 @@ jobs:
 
   - script: |
       set PATH=%PATH%;$(Build.BinariesDirectory)\doxygenexe
-      cmake -G Ninja "-DK4A_BUILD_DOCS:BOOL=ON" "-DCMAKE_VERBOSE_MAKEFILE=ON" "$(Build.SourcesDirectory)"
+      cmake -G Ninja "-DK4A_BUILD_DOCS:BOOL=ON" "-DCMAKE_VERBOSE_MAKEFILE=ON" "-DSOURCE_BRANCH=$(Build.SourceBranch)" "$(Build.SourcesDirectory)"
 
     workingDirectory: '$(Build.BinariesDirectory)'
     displayName: 'CMake Configure'
@@ -459,6 +460,14 @@ jobs:
       parallel: true
       parallelCount: 8
 
+  - task: PowerShell@2
+    displayName: 'Publish Documentation HTML'
+    inputs:
+      targetType: 'filePath'
+      filePath: '$(Build.SourcesDirectory)\doxygen\PublishDocs.ps1'
+    condition: and(eq(variables['System.CollectionId'], 'cb55739e-4afe-46a3-970f-1b49d8ee7564'), and(succeeded(), ne(variables['Build.Reason'], 'PullRequest')))
+
+
 - ${{ if eq(variables['System.CollectionId'], 'cb55739e-4afe-46a3-970f-1b49d8ee7564') }}:
   - job: WindowsFunctionalTests
     displayName: Windows Functional Test

docs/usage.md

@@ -43,3 +43,8 @@ into this repo under scripts/99-k4a.rules. To do so:
 * Detach and reattach Azure Kinect devices if attached during this process.
 
 Once complete, the Azure Kinect camera is available without being root.
+
+## API Documentation
+
+See https://microsoft.github.io/Azure-Kinect-Sensor-SDK/ for the most recent API documentation, including documentation for the current
+development branch.

doxygen/Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Azure Kinect Sensor SDK"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = "@DOXYGEN_PROJECT_NUMBER@"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -253,7 +253,7 @@ TCL_SUBST              =
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored

doxygen/PublishDocs.ps1

@@ -0,0 +1,49 @@
+param(
+    $SourceBranch = ${env:Build_SourceBranch},
+    $SourcesDirectory = ${env:Build_SourcesDirectory},
+    $DocumentationPath = "${env:Build_BinariesDirectory}\docs\html"
+)
+
+$ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop;
+
+cd $SourcesDirectory;
+
+if ($SourceBranch.StartsWith('refs/heads/'))
+{
+    $SourceBranch = $SourceBranch.SubString('refs/heads/'.Length);
+}
+
+# Identity of the automated commits
+git config --local user.email "k4abot@microsoft.com"
+git config --local user.name "Azure Kinect Bot"
+
+$Authorization = "Basic " + [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes( "${env:GITHUBBOT_USER}:${env:GITHUBBOT_PAT}"))
+
+git config --local --add "http.https://github.com/.extraheader" "AUTHORIZATION: $Authorization"
+
+# Check out the documentation branch
+git checkout gh-pages -q
+git pull
+
+
+
+# Create the directory if it doesn't exist
+$DestinationDirectory = mkdir -force ([System.IO.Path]::Combine($SourcesDirectory, $SourceBranch))
+
+# Delete the directory to ensure it is empty
+rmdir -Force $DestinationDirectory -Recurse
+
+# Copy the documentation HTML to that directory
+Copy-Item -Recurse $DocumentationPath -Destination ($DestinationDirectory.FullName)
+
+
+# Find all documentation branches (any subdirectory with index.html)
+$Branches = Get-ChildItem -Recurse -Filter index.html |? { $_.Directory.FullName.Length -gt $SourcesDirectory.Length } |% { $_.Directory.FullName.Substring($SourcesDirectory.Length + 1).Replace('\', '/') } |? { -not $_.StartsWith('build/') }
+
+# Save the branch metadata in branches.js
+$Javascript = "var BRANCHES = " + (ConvertTo-Json @($Branches));
+$Javascript | Set-Content branches.js;
+
+git add *
+git commit -m "Updated documentation for $SourceBranch from commit $(${env:Build_SourceVersion})"
+git push

doxygen/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Azure Kinect Sensor SDK Documentation</title>
+  <script src="branches.js" type="text/javascript">
+  </script>
+  <script type="text/javascript">
+    console.log(BRANCHES);
+
+    window.onload = function()
+      {
+        var branchlist = document.getElementById('branchlist');
+
+        for (i = 0; i < BRANCHES.length; i++)
+        {
+          var element = BRANCHES[i];
+          var newItem = document.createElement("li");
+          var link = document.createElement("a");
+          link.href = element + "/index.html";
+          link.title = element;
+
+          var branchName = document.createTextNode(element);
+          link.appendChild(branchName);
+          newItem.appendChild(link);
+          branchlist.appendChild(newItem);
+        };
+      };
+  </script>
+</head>
+<body>
+  <h1>API Documentation</h1>
+
+  <div>
+    For the most recent stable build see <a href="master/index.html">master</a>.
+  </div>
+  <div>
+      For the most recent development build see <a href="develop/index.html">develop</a>.
+  </div>
+
+  <h2>Branches</h2>
+  <!-- List of branches populated from branches.js -->
+  <ul id="branchlist">
+
+  </ul>
+  
+</html>
+