Generate API docs from NUnit source code (#843)

* Ignore the API directory

Since we're generating it by build

* Add docfx generation commands

* Ignore code-output folder

Since that's where the release will be added

* Readme instructions for local use

* wrap

* Action to get NUnit asset

* unzip and copy

* verbose unzip

* unzip into subdir

* adjust syntax

* adjust syntax

* adjust syntax

* more

* more

* I must be a little sleepy.

* only ignore YML and manifest files

* Add API index

* Add API reference to docs index

* Adjust TOC file

* Remove index (not needed)

* Let's try out previews of the docs, because why not

* limit step to PR only

* remove context flag

only available when actually building

* Only clean up on PRs

* Update to use deploy_url

.url is for prod

* Attempt to add a preview link comment

* quick test of devcontainer script

* Let's see.

* Install unzip

* remove the zip file

* fix directory

* move instead of copy

* Set flag to overwrite

* back to copy

* more

* There we go.

* aliaa

* comments

* alias

* Contributing updates on one-liner commands

.devcontainer/Dockerfile

@@ -10,7 +10,7 @@ RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | 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
+RUN apt-get install nodejs unzip -y
 
 ### Installing Node Packages
 RUN npm install -g yarn
@@ -22,6 +22,10 @@ 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 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
@@ -30,3 +34,7 @@ RUN echo 'first_workspace=\"$(cd /workspaces && ls | head -1)\"; alias lint="mar
 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/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/workflows/build-process.yml

@@ -8,6 +8,9 @@ on:
     branches:
       - master
 
+env:
+  NUNIT_VERSION_FOR_API_DOCS: "4.0.0"
+
 jobs:
   linting:
     name: "Markdown linting"
@@ -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,39 @@ 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
+      - 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 }}      
   snippets:
     name: "Build/Test Snippets"
     runs-on: ubuntu-latest

.gitignore

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

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.

docs/.gitignore

@@ -1,5 +1,10 @@
-## Specific overrides for NUNit
+#####################
+#  NUNit Specific   #
+#####################
 _exported_templates
+# ignored because we auto-generate it at build time rather than locally
+/api/*.yml
+/api/*.manifest
 
 # Because they are ignored at the root level of the source but are needed here.
 !/images**

docs/docfx.json

@@ -1,17 +1,35 @@
 {
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "code-output/**/**.dll"
+          ],
+          "src": "../"
+        }
+      ],
+      "dest": "api"
+    }
+  ],
   "build": {
     "content": [
       {
         "files": [
-          "articles/**.md", 
-          "articles/**/toc.yml", 
-          "toc.yml", 
+          "api/*.yml",
+          "articles/**.md",
+          "articles/**/toc.yml",
+          "toc.yml",
           "*.md"
         ]
       }
     ],
     "resource": [
-      { "files": "**/**", "src": "legacy", "dest": ""},
+      {
+        "files": "**/**",
+        "src": "legacy",
+        "dest": ""
+      },
       {
         "files": [
           "CNAME",
@@ -35,8 +53,13 @@
     },
     "globalMetadataFiles": [],
     "fileMetadataFiles": [],
-    "template": ["default", "custom_template"],
-    "postProcessors": [ "ExtractSearchIndex" ],
+    "template": [
+      "default",
+      "custom_template"
+    ],
+    "postProcessors": [
+      "ExtractSearchIndex"
+    ],
     "markdownEngineName": "markdig",
     "noLangKeyword": false,
     "keepFileLink": false,
@@ -46,4 +69,4 @@
       "baseurl": "http://docs.nunit.org"
     }
   }
-}
+}

docs/toc.yml

@@ -1,5 +1,4 @@
-- name: Articles
-  href: articles/
-# - name: Api Documentation
-#   href: api/
-#   homepage: api/
+- name: Articles
+  href: articles/
+- name: API Reference
+  href: api/