Merge branch 'master' into pr/807

.devcontainer/Dockerfile

@@ -1,32 +1,41 @@
-FROM ghcr.io/nunit/docfx-action:v2.10.0
-EXPOSE 8080
-ARG NODE_MAJOR=20
-
-### Installing Node LTS into the container
-RUN apt-get update
-RUN apt-get install -y ca-certificates curl gnupg
-RUN mkdir -p /etc/apt/keyrings
-RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
-
-RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
-RUN apt-get update
-RUN apt-get install nodejs -y
-
-### Installing Node Packages
-RUN npm install -g yarn
-RUN npm install -g npm
-RUN npm install -g cspell
-RUN npm install -g markdownlint-cli2
-
-RUN node -v
-RUN npm -v
-RUN yarn -v
-
-### Add the aliases
-# We get the first workspace, because there should only be one
-# This is so that when someone updates their devcontainer name, it doesn't get screwed up
-RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias spellcheck="cspell --config /workspaces/$first_workspace/cSpell.json \"/workspaces/$first_workspace/docs/**/*.md\" --no-progress"' >> ~/.bashrc
-RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias lint="markdownlint-cli2-config /workspaces/$first_workspace/.github/linters/.markdownlint.yml /workspaces/$first_workspace/docs/**/*.md"' >> ~/.bashrc
-RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias build="docfx /workspaces/$first_workspace/docs/docfx.json"' >> ~/.bashrc
-RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias serve="docfx /workspaces/$first_workspace/docs/docfx.json --serve"' >> ~/.bashrc
-RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias snippets="dotnet test /workspaces/$first_workspace/docs/snippets/Snippets.sln"' >> ~/.bashrc
+FROM ghcr.io/nunit/docfx-action:v2.10.0
+EXPOSE 8080
+ARG NODE_MAJOR=20
+
+### Installing Node LTS into the container
+RUN apt-get update
+RUN apt-get install -y ca-certificates curl gnupg
+RUN mkdir -p /etc/apt/keyrings
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+
+RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
+RUN apt-get update
+RUN apt-get install nodejs unzip dos2unix -y
+
+### Installing Node Packages
+RUN npm install -g yarn
+RUN npm install -g npm
+RUN npm install -g cspell
+RUN npm install -g markdownlint-cli2
+
+RUN node -v
+RUN npm -v
+RUN yarn -v
+
+# This script gets the api-docs from the latest NUnit release
+COPY get-nunit-apidocs.sh .
+RUN dos2unix ./get-nunit-apidocs.sh
+RUN chmod +x get-nunit-apidocs.sh
+
+### Add the aliases
+# We get the first workspace, because there should only be one
+# This is so that when someone updates their devcontainer name, it doesn't get screwed up
+RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias spellcheck="cspell --config /workspaces/$first_workspace/cSpell.json \"/workspaces/$first_workspace/docs/**/*.md\" --no-progress"' >> ~/.bashrc
+RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias lint="markdownlint-cli2-config /workspaces/$first_workspace/.github/linters/.markdownlint.yml /workspaces/$first_workspace/docs/**/*.md"' >> ~/.bashrc
+RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias build="docfx /workspaces/$first_workspace/docs/docfx.json"' >> ~/.bashrc
+RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias serve="docfx /workspaces/$first_workspace/docs/docfx.json --serve"' >> ~/.bashrc
+RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias snippets="dotnet test /workspaces/$first_workspace/docs/snippets/Snippets.sln"' >> ~/.bashrc
+
+# We load the latest NUnit apidocs at start in case they're needed later
+RUN echo 'alias apidocs="bash /get-nunit-apidocs.sh"' >> ~/.bashrc
+RUN echo 'apidocs' >> ~/.bashrc

.devcontainer/devcontainer.json

@@ -17,7 +17,8 @@
 				"shuworks.vscode-table-formatter",
 				"ms-dotnettools.csharp",
 				"github.vscode-github-actions",
-				"ms-azuretools.vscode-docker"
+				"ms-azuretools.vscode-docker",
+				"stkb.rewrap"
 			]
 		}
 	}

.devcontainer/get-nunit-apidocs.sh

@@ -0,0 +1,15 @@
+# This script gets the the latest version of NUnit and extracts it. This is because docfx is capable of generating API docs, and this way the Codespace will be automatically enabled to do that.
+
+# This is hard-coded for now.
+NUNIT_VERSION_FOR_API_DOCS="4.0.0"
+
+first_workspace="$(cd /workspaces && ls | head -1)"
+
+wget "https://github.com/nunit/nunit/releases/download/v$NUNIT_VERSION_FOR_API_DOCS/NUnit.Framework-$NUNIT_VERSION_FOR_API_DOCS.zip" -O /apidocs.zip
+
+
+mkdir -p /workspaces/$first_workspace/code-output 
+unzip -o /apidocs.zip -d /apidocs
+cp -r /apidocs/bin/net6.0/* /workspaces/$first_workspace/code-output
+rm -rf /apidocs.zip
+rm -rf /apidocs

.github/linters/.markdownlint.yml

@@ -19,7 +19,10 @@
 # Rules by id #
 ###############
 MD024: false
-MD013: false
+MD013: 
+  line_length: 120
+  code_blocks: false
+  tables: false
 MD026: false
 MD046: false # Mix of indented and fenced code blocks
 MD004: false

.github/workflows/build-process.yml

@@ -8,14 +8,17 @@ on:
     branches:
       - master
 
+env:
+  NUNIT_VERSION_FOR_API_DOCS: "4.0.0"
+
 jobs:
   linting:
     name: "Markdown linting"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         name: Check out the code
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         name: Setup node
         with:
           node-version: "18"
@@ -29,7 +32,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         name: Check out the code
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         name: Setup node
         with:
           node-version: "18"
@@ -43,6 +46,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         name: Check out the code
+      - name: Get latest NUnit Asset dir
+        uses: dsaltares/fetch-gh-release-asset@master
+        with:
+          repo: 'nunit/nunit'
+          version: 'tags/v${{ env.NUNIT_VERSION_FOR_API_DOCS }}'
+          file: 'NUnit.Framework-${{ env.NUNIT_VERSION_FOR_API_DOCS }}.zip'
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Unzip NUnit Asset zip file into its own directory
+        run: unzip NUnit.Framework-${{ env.NUNIT_VERSION_FOR_API_DOCS }}.zip -d ./NUnit.Framework-${{ env.NUNIT_VERSION_FOR_API_DOCS }}
+      - name: Copy NUnit Asset dir
+        run: mkdir ./code-output && cp -r ./NUnit.Framework-${{ env.NUNIT_VERSION_FOR_API_DOCS }}/bin/net6.0/* ./code-output
       - uses: "nunit/[email protected]"
         name: Build with Docfx
         with:
@@ -54,6 +68,41 @@ jobs:
         with:
           name: siteArtifact
           path: _site.zip
+      - name: Start deployment (PR only)
+        if: ${{ github.ref != 'refs/heads/master'}}
+        uses: bobheadxi/deployments@v1
+        id: deployment
+        with:
+          env: preview_${{github.event.number}}
+          step: start
+          token: ${{ secrets.SEAN_PAT_TO_MANAGE_ENVIRONMENTS }}
+      - name: Deploy to Netlify (PR only)
+        if: ${{ github.ref != 'refs/heads/master'}}
+        uses: South-Paw/action-netlify-cli@v2
+        id: netlify
+        with:
+          # note that the --json flag has been passed so we can parse outputs
+          args: deploy --json --dir './docs/_site' --message 'preview [${{ github.sha }}]'
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}          
+      - name: Update Preview link comment
+        if: ${{ github.ref != 'refs/heads/master'}}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: previewlink
+          message: |
+            Preview link: ${{ fromJson(steps.netlify.outputs.NETLIFY_OUTPUT).deploy_url }}          
+      - name: Finish deployment
+        uses: bobheadxi/deployments@v1
+        if: ${{ github.ref != 'refs/heads/master'}}
+        with:
+          env: ${{ steps.deployment.outputs.env }}
+          step: finish
+          status: ${{ job.status }}
+          deployment_id: ${{ steps.deployment.outputs.deployment_id }}
+          env_url: ${{ fromJson(steps.netlify.outputs.NETLIFY_OUTPUT).deploy_url }}     
+          token: ${{ secrets.SEAN_PAT_TO_MANAGE_ENVIRONMENTS }} 
   snippets:
     name: "Build/Test Snippets"
     runs-on: ubuntu-latest

.github/workflows/closed-pr.yml

@@ -0,0 +1,15 @@
+on:
+    pull_request:
+      types: [ closed ]
+jobs:
+    prune:
+      permissions: 
+        deployments: write
+      runs-on: ubuntu-latest
+      steps:
+      - name: delete environment
+        uses: bobheadxi/deployments@v1
+        with:
+            step: delete-env
+            token: ${{ secrets.SEAN_PAT_TO_MANAGE_ENVIRONMENTS }}
+            env: preview_${{github.event.number}}

.gitignore

@@ -0,0 +1 @@
+code-output/

.markdownlintrc

@@ -1,6 +1,11 @@
 {
     "MD024": false,
-    "MD013": false,
+    "MD013": {
+        "line_length": 123,
+        "code_blocks": false,
+        "tables": false
+
+    },
     "MD026": false,
     "MD046": false,
     "MD004": false

.vscode/extensions.json

@@ -0,0 +1,24 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"streetsidesoftware.code-spell-checker",
+		"oderwat.indent-rainbow",
+		"mdickin.markdown-shortcuts",
+		"davidanson.vscode-markdownlint",
+		"redhat.vscode-yaml",
+		"vsls-contrib.codetour",
+		"GitHub.vscode-pull-request-github",
+		"shuworks.vscode-table-formatter",
+		"ms-dotnettools.csharp",
+		"github.vscode-github-actions",
+		"ms-azuretools.vscode-docker",
+		"stkb.rewrap"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": [
+
+	]
+}

.vscode/settings.json

@@ -15,5 +15,9 @@
     "cSpell.enabled": true,
     "cSpell.enableFiletypes": [
         "aspnetcorerazor"
-    ]
+    ],
+    "editor.wordWrap": "wordWrapColumn",
+    "editor.wrappingIndent": "same",
+    "editor.wordWrapColumn": 120,
+    "editor.rulers": [120],
 }

CONTRIBUTING.md

@@ -59,7 +59,13 @@ You can open the repository in GitHub Codespaces. This will open an instance of
 
 * Syntax highlighting for spelling and markdown issues
 * Auto-formatting on save according to our standards
-* Simple command aliases in the terminal: `spellcheck`, `lint`, `build`, `serve`, and `snippets` will cover most folks' workflow.
+* Simple command aliases in the terminal to cover most folks' workflows:
+  * `spellcheck`: Check for spelling errors in docs
+  * `lint`: Markdown linting
+  * `build`: Use docfx to build site
+  * `serve`: Build with docfx but also serve the generated site
+  * `apidocs`: If needed, downloads the latest NUnit release to extract it to the right place so that the API documentation can generate. (This happens automatically upon startup)
+  * `snippets`: Builds the snippets projects to ensure they work.
 
 ### Option 3a: A Container Within VS Code
 

README.md

@@ -37,9 +37,24 @@ We'll be working on follow-ups to make this more user-friendly, but it's now wor
 
 We'd love your contributions! See [The contributing guide](CONTRIBUTING.md) for how to get involved.
 
+## Building the API docs locally
+
+The NUnit source code is in a separate repository from the docs, so we typically generate this at build time by copying
+published code into a build-specific folder (`/code-output`). From there, `docfx` transforms the xmldoc comments that
+are alongside the DLLs into HTML files.
+
+Sometimes you may need/want to reproduce this locally. You can take the following steps to do so:
+
+* Go to the NUnit release you want in the GitHub Releases
+* Download & extract the `.zip` file of the release contents
+* Copy the contents of one of the release targets, e.g. `net6.0`, into a `code-outputs` folder in the root of the
+repository.
+* Run the `docfx` command as you normally would.
+
 ## How the Docs are Built and Deployed
 
 * We build the docs via the GitHub actions located in `./github/workflows`.
 * The workflow uses a container with docfx installed; the container builds the docs.
-* The workflow then uses another container to push the results to the `gh-pages` branch, using a personal access token that is stored in the repository's settings.
+* The workflow then uses another container to push the results to the `gh-pages` branch, using a personal access token
+that is stored in the repository's settings.
 * GitHub serves the outputted site from the `gh-pages` branch, and the DNS of `docs.nunit.org` points there.