misc: update DocFX log file path and enhance build documentation process

Author: DennisDyallo

.github/workflows/build.yml

@@ -90,8 +90,7 @@ jobs:
       - name: Build docs
         run: |
           dotnet tool install --global docfx --version 2.78.2
-          docfx --version
-          docfx Yubico.YubiKey/src/docfx.json --logLevel warning --log Yubico.YubiKey/docs/docfx-log.txt
+          docfx Yubico.YubiKey/src/docfx.json --logLevel warning --log Yubico.YubiKey/docs/docfx.log
 
       # Upload documentation
       - name: "Save build artifacts: Docs"

.vscode/tasks.json

@@ -156,6 +156,22 @@
       ],
       "problemMatcher": "$msCompile",
       "group": "test"
+    },
+    {
+      "label": "Build DocFX Documentation",
+      "type": "shell",
+      "command": "dotnet",
+      "args": [
+        "msbuild",
+        "${workspaceFolder}/Yubico.YubiKey/src/Yubico.YubiKey.csproj",
+        "/t:DocFXBuild",
+      ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": [],
+      "detail": "Builds the documentation using DocFX"
     }
   ]
 }

Yubico.YubiKey/src/Yubico.YubiKey.csproj

@@ -155,21 +155,25 @@ limitations under the License. -->
 
   </ItemGroup>
 
-  <!-- DocFX build target runs after Release-build -->
+  <!-- Build documentation -->
+  <!-- DocFX is a tool that generates documentation from source code. It is used to generate the API documentation for the YubiKey SDK. -->
+  <!-- Run this before submitting a PR to make sure that your code does not produce any documentation issues -->
+  <!-- This can be called either by command line or in VS Code Tasks (.vscode/tasks.json) 
+    > dotnet msbuild Yubico.YubiKey/src/Yubico.YubiKey.csproj /t:DocFXBuild 
+  -->
+  <Target Name="DocFXBuild" DependsOnTargets="CheckDocFX;Restore;Build">
+    <Exec Command="docfx build $(MSBuildProjectDirectory)/docfx.json --logLevel warning --log ../docs/docfx.log --warningsAsErrors" IgnoreExitCode="true">
+      <Output TaskParameter="ExitCode" PropertyName="DocFXExitCode" />
+    </Exec>
+    <!-- Quirk. 255 seems to be the exit code it uses but we don't know the reason, so we catch it and refer to the log -->
+    <Error Condition="'$(DocFXExitCode)' != '255' AND '$(DocFXExitCode)' != '0'" Text="DocFX build failed with exit code $(DocFXExitCode). Check docfx-log.txt for details." />
+  </Target>
+
+  <!-- Check if DocFX is installed -->
   <Target Name="CheckDocFX">
     <Exec Command="docfx --version" ContinueOnError="true">
       <Output TaskParameter="ExitCode" PropertyName="DocFXExists" />
     </Exec>
     <Error Condition="'$(DocFXExists)' != '0'" Text="DocFX is not installed. Please install it using: dotnet tool install --global docfx" />
   </Target>
-
-  <Target Name="DocFXBuild" AfterTargets="Build" DependsOnTargets="CheckDocFX" Condition="'$(Configuration)' == 'ReleaseWithDocs'">
-    <Exec Command="docfx build $(MSBuildProjectDirectory)/docfx.json --logLevel warning --log docfx-log.txt --warningsAsErrors" IgnoreExitCode="true">
-      <Output TaskParameter="ExitCode" PropertyName="DocFXExitCode" />
-    </Exec>
-    <!-- Quirk. 255 seems to be the exit code it uses but we don't know the reason, so we catch it and refer to the log -->
-    <Error Condition="'$(DocFXExitCode)' != '255' AND '$(DocFXExitCode)' != '0'" 
-       Text="DocFX build failed with exit code $(DocFXExitCode). Check docfx-log.txt for details." />
-  </Target>
-
 </Project>

contributordocs/code-flow-and-pull-requests.md

@@ -106,20 +106,22 @@ better name than it is to push code that has nothing to do with the original nam
 Prior to merging into `develop`, you should check your own work for the following things:
 
 - Did I remember to document all public APIs, types, members, etc.?
-- Did I build the ReleaseWithDocs configuration and check for build errors in the examples and documentation?
+- Did I [build the documentation](./documentation-system/building-docs-and-running.md) and check for build errors in the examples and documentation?
 - Did I write unit and/or integration tests for the functionality I just added?
 
 If the answer to any one of these questions is no, please take the time to complete this task. Chances
 are you will be asked to do so anyways as part of the pull request process.
 
-✅ **DO** a full build (ReleaseWithDocs) prior to opening a pull request.
+✅ **DO** a full build and build documentation prior to opening a pull request.
 
 ✅ **CONSIDER** doing a self-review based on the branch diffs before opening a PR. Often times you can
 catch mistakes yourself this way.
 
 ❌ **DO NOT** open a pull request for code that is not ready. Draft PRs can be used for this, or you can
 direct someone to checkout your in-progress branch.
 
+> ⚠ **NOTE:** See the page on [Building the docs and running](./documentation-system/building-docs-and-running.md) page for more information on building the documentation.
+
 ### Doing the review
 
 Code reviews are meant to be educational for both the reviewers and the author. Regular code reviews allow

contributordocs/documentation-system/building-docs-and-running.md

@@ -14,8 +14,15 @@ limitations under the License. -->
 
 # Building the docs and running
 
-We have DocFX integrated into the project's build system using NuGet. Documentation is automatically
-generated when the source code is compiled.
+We use DocFX to build the documentation for the Yubico.YubiKey project. This is a tool that
+generates documentation from comments in the source code. The comments are written in Markdown
+format.
+
+In order to build the documentation, use either of the following methods: 
+1. Command Line: `docfx build Yubico.YubiKey/src/docfx.json`
+2. VS Code: Run the build task `DocFXBuild` using [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks) 
+   
+> Note: In order to run `docfx` commands, you need to have docfx installed. Install `docfx` using the following command: `dotnet tool install -g docfx`
 
 The result is in `Yubico.YubiKey/docs/_site`. The home page is `index.html`.