From ed27e988d531f99d015ee0b3eb4f4a2837bcb7c3 Mon Sep 17 00:00:00 2001 From: Anthony Truskinger Date: Fri, 12 Feb 2021 11:21:35 +1000 Subject: [PATCH] Update docs readme Trying to make the instructions even clearer --- docs/README.md | 32 +++++++++++++++++++----------- docs/guides/generic_recognizers.md | 2 +- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/README.md b/docs/README.md index 60721051f..0c2d1175e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,10 +12,10 @@ Ensure you have [Chocolatey installed](https://chocolatey.org/install). Then: choco install docfx -y ``` -To generate the docs: +To generate the docs (from audio-analysis repo root): ```powershell -../build/generate_docs.ps1 +./build/generate_docs.ps1 ``` Notes: @@ -23,32 +23,40 @@ 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: +To preview (from **audio-analysis repo root directory**), in PowerShell: -```powershell -cd _site -docfx serve -``` +1. Run the big build script first: + ```powershell + ./build/generate_docs.ps1 + ``` +1. Run the quick build command after each change: + ```powershell + docfx build ./docs/docfx.json + ``` +1. Run the _serve_ command in a _separate terminal_: -Then visit the url in your browser, typically . + ```powershell + docfx serve ./_site + ``` +1. Then visit the url in your browser, typically . ## Layout The documentation is laid out into several areas: -- **basics**: include introductory topics, like downloading, installing, and general bit of information +- **basics**: include introductory topics, like downloading, installing, and general bits 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 +- **guides**: short form workflows which can be adapted to a user's usecase - 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 +- **tutorials**: Reserved for detailed lessons, with specific working examples - **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 @@ -71,4 +79,4 @@ 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. \ No newline at end of file +This file is not published with the docs. diff --git a/docs/guides/generic_recognizers.md b/docs/guides/generic_recognizers.md index 625b190a0..7716b69b4 100644 --- a/docs/guides/generic_recognizers.md +++ b/docs/guides/generic_recognizers.md @@ -376,7 +376,7 @@ Some of these algorithms have extra parameters, some do not, but all do have the | I want to find a | I'll use this algorithm | |------------------|------------------------------------------------------------------------------------------| -| Shriek | [!BlobParameters](xref:AnalysisPrograms.Recognizers.Base.BlobParameters) 🚧 | +| Shriek | [!BlobParameters](xref:AnalysisPrograms.Recognizers.Base.BlobParameters) | | Whistle | 🚧 !HorizontalTrackParameters 🚧 | | Chirp | [!ForwardTrackParameters](xref:AnalysisPrograms.Recognizers.Base.ForwardTrackParameters) | | Whip | 🚧!UpwardsTrackParameters 🚧 |