Renable api docs generation

Also update all projects to use standard csproj msbuild SDK header.

The stackover flow that was causing docs generation to crash is caused by inheritdoc cref's that are circular (in the simlest case, referencing the member they are describing and are atacched to).

.github/workflows/docs.yml

@@ -34,19 +34,17 @@ jobs:
     # fetch more tag info so git_version.ps1 works properly
     - name: Ensure tags are fetched
       # Retrieve annotated tags.
-      run: git fetch --tags --force 
+      run: git fetch --tags --force
 
-    # disabled due to bug in docfx that leads to a stack overflow
-    # also disabled in generate_docs.ps1
     # setup and build solution
-    # - name: Setup .NET
-    #   uses: actions/setup-dotnet@v1
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v1
 
-    # - name: Restore dependencies
-    #   run: dotnet restore
+    - name: Restore dependencies
+      run: dotnet restore
 
-    # - name: Build
-    #   run: dotnet build --no-restore
+    - name: Build
+      run: dotnet build --no-restore
 
     - name: Generate docs
       shell: pwsh

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "cSpell.words": [
       "Arial",
+      "Browsable",
       "Ecoacoustics",
       "Hanning",
       "Roboto",

README.md

@@ -17,6 +17,8 @@ Documentation (_in progress_) can be found at <https://ap.qut.ecoacoustics.info/
 - See the **[Contributing guidelines](./CONTRIBUTING.md)** if you want to
   - Compile the code yourself
   - Make a contribution
+- Our documentation can be found at <https://ap.qut.ecoacoustics.info/>
+    - The source files are in the `docs` folder and instructions for editing them are in [`docs/README.md`](./docs/)
 - [Let us know](https://github.com/QutEcoacoustics/audio-analysis/wiki/Projects-and-people-using-AP.exe) if you're using AP.exe 
 
 ## Description

build/generate_docs.ps1

@@ -25,9 +25,8 @@ try {
     Set-Location docs
 
     log "[Disabled] Prepare API metadata for docs"
-    # metadata generation disabled due to a StackOverflowException that occurs
-    # if we try to build the docs after a metadata generation has been done
-    #exec { docfx metadata }
+
+    exec { docfx metadata }
 
     log "Building pdf docs" "Build PDF"
     exec { docfx pdf  --log verbose }

docs/README.md

@@ -6,6 +6,8 @@ You can use this tool locally to see what your documentation looks like.
 
 To install:
 
+Ensure you have [Chocolatey installed](https://chocolatey.org/install). Then:
+
 ```powershell
 choco install docfx -y
 ```
@@ -15,7 +17,9 @@ To generate the docs:
 ```powershell
 ../build/generate_docs.ps1
 ```
-Notes: 
+
+Notes:
+
 - If there are any errors or warnings they need to be fixed before your changes are committed.
 - You **must rebuild** after changes to see the updated preview
 

docs/docfx.json

@@ -3,21 +3,26 @@
     {
       "src": [
         {
-          "src": "..",
+          "src": "../src",
           "files": [
-            "src/**.csproj"
+            "AnalysisPrograms\\AnalysisPrograms.csproj",
+            "**/*.csproj"
           ],
           "exclude": [
-            "src/**.fsproj",
             "**/*.fsproj",
-            "*.fsproj",
-            "test/**"
+            "AED/*",
+            "**/*.fsproj",
+            "*.fsproj"
           ]
         }
       ],
       "dest": "technical/api",
       "disableGitFeatures": false,
-      "disableDefaultFilter": false
+      "disableDefaultFilter": false,
+      "filter": "metadata_filter.yml",
+      "properties": {
+        "TargetFramework": "net5.0"
+      }
     }
   ],
   "build": {
@@ -55,8 +60,7 @@
       {
         "files": [
           "images/**",
-          "netlify.toml",
-
+          "netlify.toml"
         ],
         "exclude": [
           "images/README.md"

docs/metadata_filter.yml

@@ -0,0 +1,19 @@
+# format: https://dotnet.github.io/docfx/tutorial/howto_filter_out_unwanted_apis_attributes.html
+# take care when changing this filter; docfx currently crashes from a stack overflow if docs for our full API are generated
+ApiRules:
+  - exclude:
+      hasAttribute:
+        uid: System.ComponentModel.EditorBrowsableAttribute
+        ctorArguments:
+          - System.ComponentModel.EditorBrowsableState.Never
+  - include:
+      uidRegex: ^.*Config.*$
+      type: Class
+  - include:
+      uidRegex: ^AnalysisPrograms\.Recognizers\.GenericRecognizer\.GenericRecognizerConfig
+  # - include:
+  #     uidRegex: ^.*Config.*$
+  #     type: Type
+  - exclude:
+      uidRegex: .*
+      type: Type

docs/technical/toc.yml

@@ -10,5 +10,5 @@
   href: ../../CODE_OF_CONDUCT.md
 - name: Commands
   href: commands/toc.yml
-# - name: API
-#   href: api/toc.yml
+- name: API
+  href: api/toc.yml

src/AcousticWorkbench/AcousticWorkbench.csproj

@@ -1,13 +1,8 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <OutputPath>bin\$(Configuration)\</OutputPath>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-    <DebugType>portable</DebugType>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-    <DebugType>pdbonly</DebugType>
+    <OutputType>Library</OutputType>
   </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
     <PackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.261">

src/Acoustics.Shared/Acoustics.Shared.csproj

@@ -1,6 +1,7 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <AssemblyTitle>Acoustics.Shared</AssemblyTitle>
+    <OutputType>Library</OutputType>
     <!-- TODO CORE: For log4net -->
     <NoWarn>$(NoWarn);NU1605</NoWarn>
   </PropertyGroup>

src/Acoustics.Shared/ImageSharp/Drawing.cs

@@ -51,7 +51,7 @@ public static class Drawing
                 //BlendPercentage = 1,
                 //ColorBlendingMode = PixelColorBlendingMode.Normal,
                 //AntialiasSubpixelDepth = 0,
-                 
+
             },
             ShapeOptions = new ShapeOptions()
             {

src/Acoustics.Shared/ImageSharp/ImageSharpExtensions.cs

@@ -281,7 +281,18 @@ public static void FillWithBlend(this IImageProcessingContext context, IBrush br
             }
         }
 
-        /// <inheritdoc cref="FillWithBlend(IImageProcessingContext, IBrush, IPath[])"/>
+        /// <summary>
+        /// Fills a rectangle with color that blends with the background.
+        /// If the given <paramref name="brush"/> contains an alpha component,
+        /// that component will be used as the <c>BlendPercentage</c> value.
+        /// </summary>
+        /// <remarks>
+        /// Apparently blending pixels with transparency is not supported for Rgb24 images.
+        /// See the FillDoesNotBlendByDefault.Test smoke test.
+        /// BUG: Blending does not occur with fill https://github.com/SixLabors/ImageSharp.Drawing/issues/38.
+        /// </remarks>
+        /// <param name="context">The drawing context.</param>
+        /// <param name="brush">The brush to fill with.</param>
         /// <param name="region">A rectangular region to fill.</param>
         public static void FillWithBlend(this IImageProcessingContext context, IBrush brush, RectangleF region)
         {
@@ -378,7 +389,7 @@ public static RectangleF AsRect(this FontRectangle rectangle)
         /// </summary>
         /// <remarks>
         /// Historically this method drew a subset of glyphs if the text was located to the left
-        /// of the image (i.e. with a negative x coordinate). 
+        /// of the image (i.e. with a negative x coordinate).
         /// </remarks>
         /// <param name="context"></param>
         /// <param name="text"></param>

src/Acoustics.Tools/Acoustics.Tools.csproj

@@ -1,14 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <AssemblyTitle>Acoustics.Tools</AssemblyTitle>
-    <OutputPath>bin\$(Configuration)\</OutputPath>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-    <DebugType>portable</DebugType>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-    <DebugType>pdbonly</DebugType>
+    <OutputType>Library</OutputType>
   </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\Acoustics.Shared\Acoustics.Shared.csproj" />
     <ProjectReference Include="..\AcousticWorkbench\AcousticWorkbench.csproj" />

src/AnalysisBase/AnalysisBase.csproj

@@ -1,13 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <AssemblyTitle>AnalysisBase</AssemblyTitle>
+    <OutputType>Library</OutputType>
   </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-    <DebugType>portable</DebugType>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-    <DebugType>pdbonly</DebugType>
-  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\Acoustics.Shared\Acoustics.Shared.csproj" />
     <ProjectReference Include="..\Acoustics.Tools\Acoustics.Tools.csproj" />

src/AnalysisBase/AnalyzerConfig.cs

@@ -31,10 +31,10 @@ public class AnalyzerConfig
         /// Gets or sets the default sample rate to re-encode all input audio as.
         /// </summary>
         /// <remarks>
-        /// ResampleRate must be 2 X the desired Nyquist.
+        /// ResampleRate must be 2× the desired Nyquist.
         /// Default value = 22050.
         /// Once upon a time we used 17640.
-        /// Units=samples
+        /// Units=samples.
         /// Users of this value should always fallback to a default appropriate for the analysis. Currently that default
         /// must be non-null, but we're considering allowing it to be null to support variable sample rate analysis.
         /// </remarks>