Publishes our documentation https://ap.qut.ecoacoustics.info

Uses DocFX to build and publish our existing documentation to netlify and ap.qut.ecoacoustics.info

Closes #313

.gitattributes

@@ -25,6 +25,8 @@
 docs/**/*.png filter=lfs diff=lfs merge=lfs -text
 docs/**/*.jpeg filter=lfs diff=lfs merge=lfs -text
 docs/**/*.jpg filter=lfs diff=lfs merge=lfs -text
+
+
 # Audio tracked with git-lfs
 *.aac     filter=lfs diff=lfs merge=lfs -text
 *.m4a     filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug_report.md

@@ -5,14 +5,16 @@ about: Create a report to help us fix a problem in AP.exe
 <!--
 Please follow the instructions in the link below before filing a bug report.
 
-https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/bug_report.md
+https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/basics/bug_report.md
 
 -->
 
 ## Describe the bug
+
 A clear and concise description of what the bug is.
 
 ## Expected behavior 
+
 A clear and concise description of what you expected to happen.
 
 ## Diagnostics
@@ -21,12 +23,12 @@ A clear and concise description of what you expected to happen.
 
 ### Instructions
 
-- [x] I have followed the [instructions for reporting a bug](https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/bug_report.md)
+✅ I have followed the [instructions for reporting a bug](https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/basics/bug_report.md)
 
 ### I have attached a log:
 
 <!-- Information about log files can be found here: -->
-<!-- https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/logs.md#log-files -->
+<!-- https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/basics/logs.md#log-files -->
 <!-- 👇 Drag and drop the log into the empty line below -->
 
 <!-- 👆 -->

.github/ISSUE_TEMPLATE/question.md

@@ -3,6 +3,11 @@ name: Ask a question
 about: I'd just like to ask a question
 ---
 
+<!-- Hi there! -->
+<!-- Please consider contacting us in gitter before making an issue -->
+<!-- https://gitter.im/QutEcoacoustics/audio-analysis -->
+
+
 ## My question
 
 <!-- Put your question here -->
@@ -13,7 +18,7 @@ about: I'd just like to ask a question
 <!-- Answer any questions you think are relevant -->
 
 - I have attached a log:
-<!-- Information about log files can be found here: https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/logs.md#log-files -->
+<!-- Information about log files can be found here: https://github.com/QutEcoacoustics/audio-analysis/blob/master/docs/basics/logs.md#log-files -->
 <!-- 👇 Drag and drop the log into the empty line below -->
 
 <!-- 👆 -->

.gitignore

@@ -231,4 +231,9 @@ Temporary Items
 .store
 .fake
 .ionide
-.fake
+.fake
+
+# docs
+_site
+.fake
+.ionide

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "cSpell.words": [
+        "Arial",
+        "Ecoacoustics",
+        "Hanning",
+        "Roboto",
+        "Tahoma",
+        "Towsey",
+        "Truskinger"
+    ]
+}

CONTRIBUTING.md

@@ -49,9 +49,9 @@ You can install it from here: https://github.com/powershell/powershell#get-power
 ### 2. A **.NET Core SDK**
 
 - We aim to use the latest stable version
-- You can verify the version our project is using by looking in the [global.json](./global.json) file
+- You can verify the version our project is using by looking in the [global.json](https://github.com/QutEcoacoustics/audio-analysis/tree/master/build/global.json) file
 
-Recommended choice is to run the `dotnet-install` script in the [./build/](./build) folder.
+Recommended choice is to run the `dotnet-install` script in the [./build/](https://github.com/QutEcoacoustics/audio-analysis/tree/master/build) folder.
 
 PowerShell:
 ```powershell

ap.code-workspace

@@ -51,5 +51,7 @@
             "titleBar.border": "#50ba1a"
         },
         "peacock.remoteColor": "#50ba1a",
+        "peacock.color": "#50ba1a",
+        "editor.minimap.size": "fill",
     }
 }

build/generate_docs.ps1

@@ -0,0 +1,28 @@
+
+
+if ($null -eq (Get-Command docfx -ErrorAction SilentlyContinue)) {
+    Wite-output "Installing docfx..."
+    #dotnet tool install -g docfx --version "3.0.0-*" --add-source https://www.myget.org/F/docfx-v3/api/v2
+    choco install docfx -y
+
+}
+
+# if (-not ((docfx --version) -match "^3.0.*")) {
+#     Write-Error "We require docfx version 3"
+# }
+
+Push-Location
+
+try {
+    Set-Location docs
+    docfx build --log verbose
+
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to build docs, skipping deploy"
+        exit 1
+    }
+}
+finally {
+    Pop-Location
+}

build/publish_docs.ps1

@@ -0,0 +1,18 @@
+Write-Output "Installing netlify CLI"
+npm install netlify-cli -g
+
+$l = $env:NETLIFY_AUTH_TOKEN.Length
+Write-Output "Environment variable NETLIFY_AUTH_TOKEN is length $l"
+
+$commit_hash = git show -s --format="%H"
+
+Push-Location
+Set-Location "$PSScriptRoot/../_site"
+
+Write-Output "Deploying to netlify"
+
+
+netlify deploy --dir=. --message="Docs deploy for https://github.com/QutEcoacoustics/audio-analysis/commit/$commit_hash" --prod --site="078c0d59-a45a-4458-bd92-2d7c05f44bb6" --json
+
+Write-Output "Deploying complete"
+Pop-Location

docs/.gitignore

@@ -0,0 +1 @@
+_exported

docs/articles/2018-05-30-Analysis-Programs-Open-Sourced.md

@@ -0,0 +1,69 @@
+---
+title: Open sourcing our analysis code
+uid: article-open-source
+---
+
+We have wanted to open source our analysis code for some time but various
+complications made this a difficult prospect. We [committed to open sourcing
+back in October](http://research.ecosounds.org/2017/10/18/about-our-platform)
+last year and we are now finally ready to announce it.
+
+We have released the *QUT Ecoacoustics Analysis Programs* software package. The
+code is on GitHub and can be found here
+<https://github.com/QutEcoacoustics/audio-analysis>. Analysis Programs is our
+(somewhat unimaginative) name for the collection of code that runs all our
+production grade analysis. The Analysis Programs software package can perform a
+suite of analyses on audio recordings of the environment. Although the analyses
+are intended for long-duration recordings (1-24 hours), in fact they can be
+performed on any duration file provided the format is supported by the software.
+Analysis Programs can:
+
+-   calculate summary and spectral acoustic indices at variable resolutions
+
+-   produce long-duration, false-colour, multi-index spectrograms
+
+-   calculate critical statistics of annotations downloaded from an Acoustic
+    Workbench
+
+-   run various acoustic event recognisers
+
+In the past, we have traditionally run this program over large datasets for
+other scientists. They would send us their data, we use our compute
+infrastructure to generate the results, and then we send the results back to the
+scientist. The good news is we're still offering that service! Even though it
+possible for anyone to run these analyses now, there are still challenges to
+running large scale analyses. As an eScience group our goal is to scale
+traditional science and we intend to keep on doing that.
+
+## The nitty-gritty details
+
+All the analyses are performed by a single executable
+file, *AnalysisPrograms.exe*, which can be run on Windows, Linux, or MacOS. The
+Mono runtime is used to run the program on non-Windows platforms.
+
+We’ve also begun writing a manual for Analysis Programs. The manual can be found
+here <https://github.com/QutEcoacoustics/audio-analysis/tree/master/docs>. It is
+currently limited in scope, but we intend to expand it in the future. We welcome
+any feedback or contributions you might have for the documentation.
+
+It has been a long process to open source the code. An important factor was the
+need to determine ownership and then remove intellectual property that we don’t
+own. However, the most significant delay for us was the nature of the software:
+this software is a critical tool for our workflows and is an active, changing,
+and always in development project. We wanted to do more than satisfy the
+bare-minimum journal requirements—more than just releasing a static,
+non-functional copy of our code from three years ago. Releasing an active
+product meant we needed to pay off our technical debt and that required changes,
+clean-up, and investments into updated tooling. For those interested you can see
+the work involved by viewing our tracking issue for the open sourcing of the
+project: <https://github.com/QutEcoacoustics/audio-analysis/issues/140>.
+
+To reflect the changing nature of the software, this repository has been setup
+to produce a weekly release that will contain new functionality and new bug
+fixes. We've also got a slew of performance improvements, new features, and bug
+fixes in the backlog.
+
+We’re keen to gather feedback. If you have any issues using our software you can
+file an [issue](https://github.com/QutEcoacoustics/audio-analysis/issues) or
+contact us on Twitter (either [@atruskie](https://twitter.com/atruskie) or
+[@QUTEcoacoustics](https://twitter.com/QUTEcoacoustics)).