Readme: remove docker, add chocolatey. Update framework targets

.github/workflows/build-APIdocs-layer.yml

@@ -6,16 +6,20 @@ on:
     paths:
     - .github/workflows/build-APIdocs-layer.yml
     - Dockerfile-metadata
+    - api-*.json
+    - build-metadata.sh
 
   push:
     branches:
     - main
     paths:
     - .github/workflows/build-APIdocs-layer.yml
     - Dockerfile-metadata
+    - /api-*.json
+    - build-metadata.sh
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 env:
@@ -41,6 +45,7 @@ jobs:
       shell: bash
 
     - name: Login to container registry
+      if: ${{ github.event_name != 'pull_request' }}
       uses: docker/login-action@v3
       with:
         registry: "${{ vars.DOCKER_REGISTRY }}"

.github/workflows/build-and-stage.yml

@@ -1,8 +1,5 @@
 name: build-website
 on:
-  workflow_run:
-    workflows: [build-api-docs]
-    types: [completed]
   pull_request:
     branches:
     - main
@@ -24,7 +21,7 @@ on:
     - "!metadata.conf"
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 permissions:
@@ -74,21 +71,20 @@ jobs:
     - name: Deploy to staging slot
       uses: azure/webapps-deploy@v3
       id: deploy-to-webapp
-      with: 
+      with:
         app-name: ${{ vars.AZURE_WEBAPP_NAME }}
         images: ${{ vars.DOCKER_REGISTRY }}/documentation:${{ env.IMAGE_TAG }}
         slot-name:  ${{ env.SLOT_NAME }}
-    
+
     - name: If PR, comment with the preview link
       if: ${{ github.event_name == 'pull_request' }}
       uses: mshick/add-pr-comment@v2
       with:
         message: |
-          ## Preview link: https://${{ vars.AZURE_WEBAPP_NAME }}-${{ env.SLOT_NAME }}.azurewebsites.net 
-          
+          ## Preview link: https://${{ vars.AZURE_WEBAPP_NAME }}-${{ env.SLOT_NAME }}.azurewebsites.net
+
           - Your changes have been deployed to the preview site. The preview site will update as you add more commits to this branch.
           - The preview link is shareable, but will be deleted when the pull request is merged or closed.
 
           > *This is an automated message.*
         repo-token: ${{ secrets.GITHUB_TOKEN }}
-

.github/workflows/build-base-layer.yml

@@ -8,7 +8,7 @@ on:
     - 'docfx/**'
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 env:

.github/workflows/pr-cleanup.yml

@@ -16,7 +16,7 @@ jobs:
       uses: azure/login@v1
       with:
         creds: ${{ secrets.AZURE_CREDENTIALS }}
-    
+
     - name: Delete slot on staging site
       run: az webapp deployment slot delete --resource-group ${{ vars.AZURE_RESOURCE_GROUP }} --name ${{ vars.AZURE_WEBAPP_NAME}} --slot ${{ env.SLOT_NAME }}
 
@@ -29,4 +29,3 @@ jobs:
         with:
           environment: "pr-${{ github.event.number }}"
           token: ${{ secrets.GITHUB_TOKEN }}
-          onlyRemoveDeployments: true

Dockerfile-metadata

@@ -1,4 +1,4 @@
-FROM steeltoe.azurecr.io/docfx:2.59.2
+FROM steeltoe.azurecr.io/docfx:2.59.4
 WORKDIR /docs
 COPY . .
 RUN ["chmod", "+x", "./build-metadata.sh"]

README.md

@@ -23,7 +23,8 @@ Visual Studio Code users may find the [Docs Authoring Pack](https://marketplace.
 
 As you get familiar with DocFX, you'll notice the addition of a YAML header in the markdown files. Values in this header let you control page design, as well as set the page's `UID`. With this, you can create `xref` as well as use DocFX's `@` shorthand. Learn more about [linking in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html).
 
-**Note** it should be very rare that you hardcode a link to an 'HTML' page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project.
+> [!NOTE]
+> It should be very rare that you hardcode a link to an 'HTML' page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project.
 
 ### Page display options
 
@@ -44,7 +45,7 @@ In the YAML header of a page's markdown, you have options to turn page elements
 
 ## Creating a new blog post
 
-Create a new `.md` file in the `articles` directory. Name the file something that is URL safe. In `/articles/index.md` add a shorthand link to the document as well as a short description. If the post should also be included in Steeltoe's RSS feed, add a link entry in `articles/rss.xml`.
+Create a new `.md` file in the `articles` directory. Name the file something that is URL safe. In `/articles/index.md` add a shorthand link to the document as well as a short description.
 
 Here is a starter blog post:
 
@@ -98,34 +99,21 @@ Corresponding entry in `api/v2/toc.yml`:
 
 ## Installing DocFX
 
-Install DocFX using one of 2 options: download from DocFX or use Docker image.
+> [!NOTE]
+> This project currently expects DocFX version 2.59.4 to be available.
 
-### Download from DocFX
+### Install with Chocolatey
 
-Download DocFX [distribution](https://github.com/dotnet/docfx/releases/).
-Unzip to directory of your choosing and add that directory to your `PATH`.
-If running on Linux or OS X, you will need to [install Mono](https://www.mono-project.com/docs/getting-started/install/) and use `mono` to execute the DoxFX binary.
-See the script in this repository at path `docfx/docfx` for an example wrapper script.
+If you are using Windows, this is the easiest method. Run this command from an elevated shell: `choco install docfx -y --version 2.59.4`
 
-### Docker Image
+### Download from DocFX
 
-You can build a Docker image with the DocFX binary and use the Powershell script `docfx.ps1` to run the image.
-`docfx.ps1` mounts the project directory in the Docker container and passes any arguments to the `docfx` command in the container.
+> [!IMPORTANT]
+> If running on Linux or OS X, you will need to [install Mono](https://www.mono-project.com/docs/getting-started/install/) and use `mono` to execute the DocFX binary.
 
-To build the Docker image:
-
-```
-$ docker build docfx --file "docfx/Dockerfile"
-```
-
-Sample invocation:
-
-```
-$ ./docfx.ps1 --version
-docfx 2.59.2.0
-Copyright (C) 2022 ? Microsoft Corporation. All rights reserved.
-This is open-source software under MIT License.
-```
+- Download DocFX [distribution](https://github.com/dotnet/docfx/releases/v2.59.4).
+- Unzip to directory of your choosing and add that directory to your `PATH`.
+- See the script in this repository at path `docfx/docfx` for an example wrapper script.
 
 ## Building and running the site
 
@@ -141,32 +129,34 @@ Building the API docs is not required for the site to run locally.
 
 If needed, these commands will download the Steeltoe source code and generate API documentation from the triple-slash comments in the codebase.
 
-```
-$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v2 -b release/2.5
-$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v3 -b release/3.2
-$ git clean -fX api
-$ docfx metadata api-v2.json
-$ docfx metadata api-v3.json
-$ docfx metadata api-all.json
+```bash
+git clone https://github.com/SteeltoeOSS/Steeltoe sources/v2 -b release/2.5
+git clone https://github.com/SteeltoeOSS/Steeltoe sources/v3 -b release/3.2
+git clean -fX api
+docfx metadata api-v2.json
+docfx metadata api-v3.json
+docfx metadata api-all.json
 ```
 
+> This process can take a while to complete, will display many warnings and may increase build time in subsequent runs of `docfx build`.
+
 ### Build the site docs
 
-This documentation site is interconnected with Steeltoe's [main site](https://github.com/SteeltoeOSS/MainSite). In order to run the two together, the appropriate main-site.json file variant is used to identify where the main site is running.
+This documentation site is expected to run alongside Steeltoe's [main site](https://github.com/SteeltoeOSS/MainSite). In order to run the two together, first use the instructions from the MainSite project to start that site, then use the appropriate main-site.json file variant described below to identify where the main site is running.
 
-```
+```bash
 # main site -> https://steeltoe.io
-$ docfx build --globalMetadataFiles main-site.json
+docfx build --globalMetadataFiles main-site.json
 
-# main site -> https://dev.steeltoe.io
-$ docfx build --globalMetadataFiles main-site.dev.json
+# main site -> https://staging.steeltoe.io
+docfx build --globalMetadataFiles main-site.staging.json
 
-# main site -> http://localhost:9081
-$ docfx build --globalMetadataFiles main-site.localhost.json
+# main site -> http://localhost:8080
+docfx build --globalMetadataFiles main-site.localhost.json
 ```
 
 ### Run local HTTP server
 
-```
-$ docfx serve _site -p 9082
+```bash
+docfx serve _site -p 8082
 ```

api-all.json

@@ -15,7 +15,7 @@
     "disableDefaultFilter": false,
     "filter": "api-filter.yml",
     "properties": {
-      "TargetFramework": "netcoreapp3.1"
+      "TargetFramework": "net6.0"
     },
     "version": "2.all"
   },
@@ -34,7 +34,7 @@
     "disableDefaultFilter": false,
     "filter": "api-filter.yml",
     "properties": {
-      "TargetFramework": "net5.0"
+      "TargetFramework": "net6.0"
     },
     "version": "3.all"
   }

api-filter.yml

@@ -19,4 +19,4 @@ apiRules:
 # Excluding Steeltoe.Messaging.RabbitMQ.Support.RabbitMessageBuilder class clears issue #147
 - exclude:
     uidRegex: ^Steeltoe\.Messaging\.RabbitMQ\.Support\.RabbitMessageBuilder
-    type: Class
+    type: Class

api-v2.json

@@ -15,7 +15,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -34,7 +34,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -53,7 +53,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -72,7 +72,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -91,7 +91,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -110,7 +110,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -129,7 +129,7 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     },
@@ -148,9 +148,9 @@
       "disableDefaultFilter": false,
       "filter": "api-filter.yml",
       "properties": {
-        "TargetFramework": "netcoreapp3.1"
+        "TargetFramework": "net6.0"
       },
       "version": "2.x"
     }
   ]
-}
+}