Updates docs

- docs now includes metdata for version of code they were built from - removed empty supported platforms doc - neatened up and fixed errors on installing.md (and in asset chooser) - added a readme to the doc folder - added alternate method of retrieving branch name in git_version script
QutEcoacoustics · Apr 22, 2020 · 1e8e33c · 1e8e33c
1 parent 9a97637
commit 1e8e33c
Show file tree

Hide file tree

Showing 12 changed files with 171 additions and 1,932 deletions.
diff --git a/build/generate_docs.ps1 b/build/generate_docs.ps1
@@ -11,9 +11,18 @@ if ($null -eq (Get-Command docfx -ErrorAction SilentlyContinue)) {
 #     Write-Error "We require docfx version 3"
 # }
 
-Push-Location
+Write-Output "Extracting git version metadata"
+. $PSScriptRoot/../src/git_version.ps1  | Split-String "`n", "`r"  -RemoveEmptyStrings | ForEach-Object { $result = @{} } { 
+    $key, $value = $_ -split "="
+    $result.Add("AP_$key", $value )
+} { $result } | ConvertTo-JSON | Out-File "$PSScriptRoot/../docs/apMetadata.json"
+
+
+
 
 try {
+    Write-Output "Startign docs build"
+    Push-Location
     Set-Location docs
     docfx build --log verbose
 

diff --git a/build/publish_docs.ps1 b/build/publish_docs.ps1
@@ -3,6 +3,10 @@ npm install netlify-cli -g
 
 $l = $env:NETLIFY_AUTH_TOKEN.Length
 Write-Output "Environment variable NETLIFY_AUTH_TOKEN is length $l"
+if ($l -eq 0) {
+    Write-Error "Netlify auth token not available, stopping"
+    exit 1
+}
 
 $commit_hash = git show -s --format="%H"
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1,6 @@
-_exported
+_exported
+
+# apMetadata json is templated so we only want to store defaults and ignore future changes
+apMetadata.json
+
+verbose
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,70 @@
+# AP.exe docs
+
+We use a tool called [DocFX](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html) to generate these docs.
+
+You can use this tool locally to see what your documentation looks like.
+
+To install:
+
+```powershell
+choco install docfx -y
+```
+
+To generate the docs:
+
+```powershell
+cd docs
+docfx build
+```
+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
+
+To preview (from audio-analysis repo root), run the _serve_ command in a separate terminal:
+
+```powershell
+cd _site
+docfx serve
+```
+
+Then visit the url in your browser, typically <http://localhost:8080>.
+
+## Layout
+
+The documentation is layed out into several areas:
+
+- **basics**: include introductory topics, like downloading, installing, and general bit of information
+- **theory**: is reserved for pages discussing theory like:
+    - how audio algorithms work
+    - how noise removal works
+    - what the indices are
+    - how indices are calculated
+    - which event detection algorithms we have
+- **guides**: short form workflows
+    - if I have audio and I want a spectrogram I do ...
+    - if I have audio and I want a FCS I do ...
+    - if I have indices and I want FCS I do...
+    - if I have segmented FCS/indices and I want them joined i do...
+- **tutorials**: Reserved for detailed lessons
+- **FAQ**: as you expect, duplicated in basics
+- **Articles**: news/blog posts etc
+- **Documentation**: is the _technical_ folder and hides anything that is too technical for general users
+
+## Contributing guidelines
+
+- the `docfx` build must produce no errors or warnings
+- do not duplicate content
+    - use cross references to refer to content in other parts of the site
+    - if something is common you can reactor it out into it's own fragment and
+      include the result in both places
+- cross reference things as much as possible
+    - the target document should have a `uid` entry at the top of the file (looks for other examples)
+    - you can use `<xref:some-uid>` to reference the target
+
+## Publish docs
+
+Use `../build/generate_docs.ps1` and then `../build/publish_docs.ps1.`
+
+Note the `NETLIFY_AUTH_TOKEN` environment variable must be defined.
+
+This file is not published with the docs.
diff --git a/docs/basics/assetChooser.html b/docs/basics/assetChooser.html
@@ -4,50 +4,54 @@
         <form id="assetChooser" class="form">
             <fieldset id="osSet" class="form-group">
                 <legend>What operating system do you use?</legend>
-                <p>Common choices:</p>
-                <ul>
-                    <div class="radio">
-                        <label>
-                            <input type="radio" name="os" value="win" checked>
-                            Windows
-                        </label>
-                    </div>
-                    <div class="radio">
-                        <label>
-                            <input type="radio" name="os" value="linux">
-                            Linux
-                        </label>
+                <div
+                    style="display: flex; align-items: flex-start; justify-items: flex-start; justify-content: space-between;">
+                    <div>
+                        <p>Common choices:</p>
+                        <div class="radio ">
+                            <label>
+                                <input type="radio" name="os" value="win" checked>
+                                Windows
+                            </label>
+                        </div>
+                        <div class="radio">
+                            <label>
+                                <input type="radio" name="os" value="linux">
+                                Linux
+                            </label>
+                        </div>
+                        <div class="radio">
+                            <label>
+                                <input type="radio" name="os" value="osx">
+                                Mac OSX
+                            </label>
+                        </div>
                     </div>
-                    <div class="radio">
-                        <label>
-                            <input type="radio" name="os" value="osx">
-                            Mac OSX
-                        </label>
+                    <div>
+                        <p>Expert choices:</p>
+                        <div class="radio">
+                            <label>
+                                <input type="radio" name="os" value="linux-musl">
+                                Linux (Alpine)
+                                <br />
+                                <small>(choose for a container)</small>
+                            </label>
+                        </div>
+                        <div class="radio">
+                            <label>
+                                <input type="radio" name="os" value="any">
+                                Any
+                                <br />
+                                <small>(choose for a run anywhere version, requires a dotnet core runtime
+                                    install)</small>
+                            </label>
+                        </div>
                     </div>
-                </ul>
-                <p>Expert choices:</p>
-                <ul>
-                    <div class="radio">
-                        <label>
-                            <input type="radio" name="os" value="linux-musl">
-                            Linux (Alpine)
-                            <br />
-                            <small>(choose for a container)</small>
-                        </label>
-                    </div>
-                    <div class="radio">
-                        <label>
-                            <input type="radio" name="os" value="any">
-                            Any
-                            <br />
-                            <small>(choose for a run anywhere version, requires a dotnet core runtime install)</small>
-                        </label>
-                    </div>
-                </ul>
+                </div>
             </fieldset>
             <fieldset id="archSet">
                 <legend>What is your CPU architecture?</legend>
-                <ul>
+                <div>
                     <div class="radio">
                         <label>
                             <input type="radio" name="arch" value="x64" checked>
@@ -75,7 +79,7 @@
                             </small>
                         </label>
                     </div>
-                </ul>
+                </div>
                 <div class="NOTE alert alert-info">
                     <h5>Note</h5>
                     <p>
@@ -85,7 +89,7 @@ <h5>Note</h5>
             </fieldset>
             <fieldset id="debugSet">
                 <legend>Do you need to debug this?</legend>
-                <ul>
+                <div>
                     <div class="radio">
                         <label>
                             <input type="radio" name="debug" value="yes">
@@ -98,7 +102,7 @@ <h5>Note</h5>
                             No
                         </label>
                     </div>
-                </ul>
+                </div>
                 <div class="NOTE alert alert-info">
                     <h5>Note</h5>
                     <p>

diff --git a/docs/basics/installing.md b/docs/basics/installing.md
@@ -25,44 +25,39 @@ to setup and install _AP.exe_
 
 The automatic install will download AP.exe and may install required perquisites.
 
-1. Perquisite: install Powershell 6+
-    - Go to <https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7>
+1. Prerequisite: install Powershell 6+
+    - Go [here](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7) to install PowerShell
 2. Run the following command in a PowerShell prompt:
 
-Automatic install command:
 
 # [Windows](#tab/windows-automatic)
-
 Run the following command in an elevated (_Run as Administrator_) prompt:
 
 ```
 PowerShell -NoProfile -ExecutionPolicy Bypass -Command "$t = \"$env:Temp\download_ap.ps1\"; (New-Object System.Net.WebClient).DownloadFile('https://raw.githubusercontent.com/QutEcoacoustics/audio-analysis/master/build/download_ap.ps1', $t); & $t; rm $t"
 ```
-
 # [Linux](#tab/linux-automatic)
-
 Run the following command:
 
 ```
 sudo pwsh -NoProfile -ExecutionPolicy Bypass -Command "\$t = \"\$env:Temp/download_ap.ps1\"; (New-Object System.Net.WebClient).DownloadFile('https://raw.githubusercontent.com/QutEcoacoustics/audio-analysis/master/build/download_ap.ps1', \$t); & \$t; rm \$t"
 ```
-
 # [MacOSX](#tab/osx-automatic)
-
 Run the following command in _Terminal_:
 
 ```
 sudo pwsh -NoProfile -ExecutionPolicy Bypass -Command "\$t = \"\$env:Temp/download_ap.ps1\"; (New-Object System.Net.WebClient).DownloadFile('https://raw.githubusercontent.com/QutEcoacoustics/audio-analysis/master/build/download_ap.ps1', \$t); & \$t; rm \$t"
 ```
-
 ***
 
+<br />
+
 > [!NOTE]
 > Please inspect
 > https://github.com/QutEcoacoustics/audio-analysis/blob/master/build/download_ap.ps1
-> prior to running ensure safety. We already know it's safe, but you should verify
+> prior to running to ensure safety. We already know it's safe, but you should verify
 > the security and contents of any script from the internet you are not familiar
-> with. All of these scripts download a remote PowerShell script and execute it on
+> with. The above command downloads a remote PowerShell script and executes it on
 > your machine.
 
 ## Manual Install
@@ -79,6 +74,8 @@ sudo pwsh -NoProfile -ExecutionPolicy Bypass -Command "\$t = \"\$env:Temp/downlo
 7. Make sure any [Prerequisites](#prerequisites) are installed
 6. Finally, check the install by running:
 
+Run the following command:
+
 # [Windows](#tab/windows-automatic)
 ```bash
 C:\AP\AnalysisPrograms.exe CheckEnvironment

diff --git a/docs/basics/supported_platforms.md b/docs/basics/supported_platforms.md
diff --git a/docs/basics/toc.yml b/docs/basics/toc.yml
@@ -1,7 +1,5 @@
 - name: Introduction
   href: introduction.md
-- name: Supported Platforms
-  href: supported_platforms.md
 - name: Installing
   href: installing.md
 

diff --git a/docs/docfx.json b/docs/docfx.json
@@ -42,7 +42,8 @@
           "**/toc.yml"
         ],
         "exclude": [
-          "images/README.md"
+          "images/README.md",
+          "README.md"
         ]
       }
     ],
@@ -80,7 +81,9 @@
         "repo": "https://github.com/QutEcoacoustics/audio-analysis"
       }
     },
-    "globalMetadataFiles": [],
+    "globalMetadataFiles": [
+      "apMetadata.json"
+    ],
     "fileMetadataFiles": [],
     "template": [
       "default",

diff --git a/docs/templates/AP/partials/footer.tmpl.partial b/docs/templates/AP/partials/footer.tmpl.partial
@@ -0,0 +1,19 @@
+
+<footer>
+  <div class="grad-bottom"></div>
+  <div class="footer">
+    <div class="container">
+      <div style="display:flex;justify-content:space-between">
+        {{{_appFooter}}}
+        {{^_appFooter}}<span>Generated by <strong>DocFX</strong></span>{{/_appFooter}}
+        <span>
+          AP docs version: <a href="{{{_gitContribute.repo}}}/tree/{{{AP_CommitHash}}}" >{{{AP_InformationalVersion}}}</a>
+        </span>
+        <span class="">
+          <a href="#top">Back to top</a>
+        </span>
+      </div>
+    </div>
+  </div>
+</footer>
+<meta name="date" itemprop="date" content="{{{AP_BuildDate}}}"/>