Add utility for clean builds and link checks; update README accordingly (#53)

* Resolve issues #24 & #43

- Add a powershell script to clean files and check links
- Add stuff in README regarding the bullet point above including a dedicated section
- Fix typos in README

Miscellaneous:
- docfx.json files entry refactored to be more succinct
- index.md configured with landing page metadata in docfx.json and
  removed relevant metadata from the file itself

Author: cjsha

README.md

@@ -31,6 +31,7 @@ Download and install [git](https://git-scm.com/downloads) if it is not installed
     ``` console
     git submodule update --recursive --init
     ```
+    In particular, the source code is available in this repo as a submodule. This will update the source code to the latest commit on main.
 1. Configure the docfx version and restore docfx companion tools such as [DocLinkChecker](https://github.com/Ellerbach/docfx-companion-tools/tree/main/src/DocLinkChecker).
 
     ``` console
@@ -49,10 +50,7 @@ Download and install [git](https://git-scm.com/downloads) if it is not installed
 
 ## Build Documentation Locally
 
-> [!NOTE]  
-> The following steps should be be performed in Powershell.
-
-To build the docs and serve locally, run:
+To build the docs and serve locally, run in PowerShell:
 
 ``` console
 ./build.ps1 --serve
@@ -74,7 +72,7 @@ git submodule update --recursive --remote
 
 ## Before Pushing
 
-The following three commands are run remotely by remote GitHub Actions serve upon pushing to a branch. The branch will not be able to merge to main unless all three commands completely successfully without any errors. Confirm that that they can complete successfully without errors locally before committing and pushing. Otherwise, the branch becomes cluttered with potentially several attempts to pass the link-check process. Run: 
+The following three commands are run remotely by remote GitHub Actions serve upon pushing to a branch. The branch will not be able to merge to main unless all three commands complete successfully without any errors. Confirm that they can complete successfully without errors locally before committing and pushing. Otherwise, the branch becomes cluttered with potentially several attempts to pass the link-check process. Run: 
 
 ``` console
 .\build.ps1 --logLevel Warning --warningsAsErrors
@@ -83,6 +81,8 @@ dotnet DocLinkChecker -v -f .github/workflows/DocLinkChecker.config
 
 If the above command fails because "you must install or update .NET", follow the URL from the failed command's output or [this one](https://dotnet.microsoft.com/en-us/download/dotnet/6.0/runtime?cid=getdotnetcore&os=windows&arch=x64) to download and install .NET runtime 6. Dotnet supports simultaneous installation of several .NET runtime versions, and version 6 is required to run the DocLinkChecker.
 
+The above set of commands can also be run using the `docfx-util.ps1` Powershell script. Specifically, run `./docfx-util.ps1 -d` in the repo's root directory. 
+
 To run the next command, install [Lychee](https://github.com/lycheeverse/lychee?tab=readme-ov-file) by following [these instructions](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation). If you are use Windows and download a Lychee executable, amend the below command according to the location and version of your Lychee executable, and run it.
 
 ``` console
@@ -91,6 +91,26 @@ To run the next command, install [Lychee](https://github.com/lycheeverse/lychee?
 
 If you use a different operating systems and a different methods of installation, the above command might require additional amendments. 
 
+The above command can also be run using the `docfx-util.ps1` Powershell script. Specifically, run `./docfx-util.ps1 -l <path/to/lychee.exe>` in the repo's root directory. 
+
+All three link-checking commands can be run with the following command: `./docfx-util.ps1 -a` in the repo's root directory. This command additionally cleans remaining artifacts from past builds before performing all the link-checking commands. This is the most robust and expedient way to confirm that the repo will pass the link checks when pushed. 
+
+### docfx-utils.ps1
+
+This is summary of docfx-utils.ps1 list members. They are described above, but they are also described below for ease-of-finding:
+
+- `docfx-utils.ps1 -c` cleans cached files/removes artifacts from previous builds.
+- `docfx-utils.ps1 -b` exports SVGs and builds the docs.
+- `docfx-utils.ps1 -l <path/to/lychee.exe>` checks for broken/missing links and references.
+- `docfx-utils.ps1 -a <path/to/lychee.exe>` performs all of the above steps.
+
+`docfx-utils.ps1 -l` and `docfx-utils.ps1 -a` will not run without a path to a lychee executable.   
+
+> [!NOTE]  
+> The docfx-utils.ps1 script (.ps1 PowerShell scripts in general) must be run in PowerShell.
+
+These commands do not serve the docs. Serve them by running `dotnet docfx serve`.
+
 ## `dotnet docfx`
 
 Running `dotnet docfx` runs both the `dotnet docfx metadata` command and the `dotnet docfx build` command in that order. Unless specified otherwise, `dotnet docfx` uses the `docfx.json` as its config file.
@@ -152,7 +172,7 @@ If local html pages don't appear to be updating, hard refresh website pages in b
 If there are discrepancies between local and remote builds:
 
 * Confirm local and remote docfx versions are consistent. This inconsistency can occur when, for example, running `docfx` instead of `dotnet docfx` or running `dotnet tool restore --configfile <configfile>` on another config file other than the one in this repo.
-* Clear the local files to remove any cached files that aren't available remotely. Such files exist in the `api` directory (though care to not delete the `.gitignore` in that directory), the `_site` directory, and the workflows directory.
+* Clear any locally cached files that aren't available remotely. Such files exist in the `api` directory (though care to not delete the `.gitignore` in that directory), the `_site` directory, and the workflows directory. Run `./docfx-util.ps1 -c` to clean artifacts from previous builds. 
 
 ## Docs Maintainability
 

docfx-utils.ps1

@@ -0,0 +1,55 @@
+
+[CmdletBinding(PositionalBinding=$false)]
+param 
+(
+    [parameter(mandatory=$false)][switch][Alias("c")]$clean,
+    [parameter(mandatory=$false)][switch][Alias("b")]$build,
+    [parameter(mandatory=$false)][string][Alias("l")]$linkcheck,
+    [parameter(mandatory=$false)][string][Alias("a")]$all
+)
+
+# this is called removeartifacts instead of clean because clean might be already mean something in powershell?
+function removeartifacts
+{
+    $deletePaths = ".\workflows\**\*.svg", ".\api\*.yml", ".\api\.manifest", ".\_site\", ".\_raw\", ".\_view\"
+    foreach($deletePath in $deletePaths){if (Test-Path $deletePath){Remove-Item $deletePath -Recurse}}
+    Write-Output ""
+}
+
+function build{.\build.ps1 --logLevel Warning --warningsAsErrors}
+
+function linkcheck 
+{
+    param($lycheePath)
+    Write-Output "`nRunning DocLinkChecker... (step one)"
+    Write-Output "------------------------------------------`n"
+    dotnet DocLinkChecker -v -f .github/workflows/DocLinkChecker.config
+    Write-Output "`nRunning lychee... (step two)"
+    Write-Output "------------------------------------------`n"
+    Invoke-Expression "& `"$lycheePath`" --no-progress --base _site --exclude ^https://github\.com.*merge.* --exclude ^https://github\.com.*apiSpec.* '_site/**/*.html'"
+    Write-Output "`n"
+}
+
+if ($clean){removeartifacts}
+
+if ($build){build}
+
+if ($PSBoundParameters.ContainsKey("linkcheck")){linkcheck($linkcheck)}
+
+if ($PSBoundParameters.ContainsKey("all"))
+{
+    Write-Output "`n------------------------------------------"
+    Write-Output "Cleaning artifacts..."
+    Write-Output "------------------------------------------"
+    removeartifacts
+    Write-Output "------------------------------------------"
+    Write-Output "Exporting SVGs & building docs..."
+    Write-Output "------------------------------------------`n"
+    Start-Sleep -Seconds 2
+    build
+    Write-Output "`------------------------------------------"
+    Write-Output "Running linkchecks... (two step process)"
+    Write-Output "------------------------------------------"
+    Start-Sleep -Seconds 2
+    linkcheck($all)
+}

docfx.json

@@ -14,22 +14,20 @@
     }
   ],
   "build": {
+    "fileMetadata": {
+      "_layout": {
+        "index.md": "landing"
+      }
+    },
     "content": [
       {
         "files": [
-          "api/**.yml",
-          "api/**.md"
-        ]
-      },
-      {
-        "files": [
-          "articles/**.md",
-          "articles/**/toc.yml",
-          "tutorials/**.md",
-          "tutorials/**/toc.yml",
-          "toc.yml",
-          "*.md"
-        ]
+          "api/**/*.{md,yml}",
+          "articles/**/*.{md,yml}",
+          "tutorials/**/*.{md,yml}",
+          "*.{md,yml}"
+        ],
+        "exclude": ["filter.yml"]
       }
     ],
     "resource": [

index.md

@@ -1,7 +1,6 @@
 ---
 uid: index
 title: OpenEphys.Onix1
-_disableBreadcrumb: true
 ---
 
 > [!Warning]