Update local build instructions and README

.gitignore

@@ -1,8 +1,8 @@
 /api/browser/**/*.manifest
 /api/browser/**/*.yml
 /obj/
-/build/
 /sources/
+/_site/
 /tools/
 /.vscode/
 /.vs/

Dockerfile

@@ -1,11 +1,11 @@
 FROM steeltoe.azurecr.io/documentation-metadata:3.2.0-2.5.5-6 AS build
 WORKDIR /docs
 COPY . .
-RUN docfx build -o build --globalMetadataFiles host.json
+RUN docfx build -o build --globalMetadataFiles main-site.json
 
 FROM nginx:1.19
 RUN rm -rf /usr/share/nginx/html
-COPY --from=build /docs/build/_site /usr/share/nginx/html
+COPY --from=build /docs/_site /usr/share/nginx/html
 COPY nginx.conf /etc/nginx/conf.d/default.conf
 COPY docker/ /
 COPY *.env /etc/documentation-site/

README.md

@@ -2,34 +2,27 @@
 
 ## Overview
 
-This is the home of Steeltoe documentation and blog articles. The site uses [DocFX](https://dotnet.github.io/docfx) to convert markdown to HTML, as well as site navigation. To get the DocFX CLI, visit [this](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html) page to see the different distributions.
+This is the home of Steeltoe documentation and blog articles. The site uses [DocFX](https://dotnet.github.io/docfx) to convert Markdown to HTML and generate site navigation.
+See [DocFX Flavored Markdown](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html) to learn more about DocFX's enhanced Markdown syntax.
 
-If you are using [VS Code](https://code.visualstudio.com/) as your editor, you can use *most* of the features included in Microsoft's [docs authoring pack](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack).
+| Path | Description
+| --- | ---
+| `/api` | API documentation
+| `/articles` | blog posts
+| `/template` | theming
 
-## Folders
+## DocFX Markdown
 
-- /api: holds the project documentation markdown and table of contents
-  - /v2: version 2 documentation
-    - /all: this holds generated API docs from doc-comments in source code
-  - /v3: version 3 documentation
-    - /all: this holds generated API docs from doc-comments in source code
-- /articles: holds the markdown for blog posts
-- /images: the images
-- /template/steeltoe: odd files that overwrite the default DocFX theme
+DocFX offers an enhanced flavor of Markdown. To see examples and learn more, view the [DocFX Flavored Markdown](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html) documentation.
+Visual Studio users may find the [Docs Authoring Pack](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack) extension pack useful.
 
 ## Markdown parser
 
-DocFX offers a custom flavor of markdown with quite a few enhanced capabilities. To see examples and learn more, view the [DocFX Flavored Markdown specification](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html?tabs=tabid-1%2Ctabid-a).
-
-### Links and Cross References
-
-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.
+DocFX offers an enhanced flavor of Markdown. To see examples and learn more, view the [DocFX Flavored Markdown](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html) documentation.
 
 ## Creating a new blog post
 
-Create a new `.md` file in the `articles` folder. Name the file something authentic that is URL-safe. Then in `/articles/index.md`, include a shorthand link to the document, as well as a short description.
+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`.
 
 Here is a starter blog post:
 
@@ -53,7 +46,8 @@ Let's talk about something really cool...
 
 ## Creating a new API document
 
-Similar to the blog post, you're going to create a new markdown file, but in the `api` folder. The name needs to be URL-safe. Notice in the api folder, there is a `v2` and `v3` subfolder. Within each of those are folders for each component. Place your content accordingly. To include the file in the table of contents, add it in `api/(version)/toc.yml`. Notice in the example below that the `topicHref` values are not absolute paths. DocFX will calculate everything at build time.
+Create a new markdown file in the `api` directory. Name the file something URL safe. In the `api` directory there are `v2` and `v3` directories. Within each of those are directories for each component. Place your content accordingly. To include the document in the Table of Contents, add it to `api/(version)/toc.yml`.
+An example API document:
 
 An example API doc:
 
@@ -71,77 +65,77 @@ Or you could link to the v3 version of this doc: @api/v3/circuitbreaker/hystrix
 Or do the same thing by providing custom link text: [view the v3 version](xref:api/v2/circuitbreaker/hystrix)
 ```
 
-The corresponding entry in api/v2/toc.yml:
+Corresponding entry in `api/v2/toc.yml`:
 
-```yml
+```yaml
 - name: Circuit Breakers
   items:
     - topicHref: circuitbreaker/hystrix.md
       name: Hystrix
 ```
 
-## Page display options
+## Installing DocFX
 
-In the YAML header of a page's markdown, you have options to turn page elements on or off. Below are those options.
+Install DocFX using one of 2 options: download from DocFX or use Docker image.
 
-|Yaml label  |Default value  |Description   |
-|---------|---------|---------|
-|_disableToc     |false|Turn off the left hand table of contents         |
-|_disableAffix     |false|Turn off the right hand page navigation links         |
-|_disableContribution     |false|Turn off right hand link to "edit this page"         |
-|_disableFooter     |false|Don't show footer when guest scrolls to page bottom         |
-|_enableSearch     |true|Show the search icon         |
-|_enableNewTab     |true|All links on the page open in a new browser tab         |
-|_disableNav     |false|Do not show top navigation links         |
-|_hideTocVersionToggle|false     |Hide the version toggler in the table of contents         |
-|_noindex     |false|Do not let search engines index the page         |
-|_disableNavbar|false     |Do not show top bar of page         |
+### Download from DocFX
 
-## Building the site
+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 [docfx/docfx](docfx/docfx) for an example wrapper script.
 
-Use DocFX's [user manual](https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html) to build and run the site in a few different ways. The simplest way is to `cd` into the root folder of this project and run the following command. The site will build in a temporary folder named `_site` and be served at <http://localhost:8082>.
+### Docker Image
 
-```powershell
-docfx build --serve --port 8082
-```
+You can build a Docker image with the DocFX binary and use the Powershell script `docfx.ps` 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.
 
-You can also specify where the build output should land
+To build the Docker image:
 
-```powershell
-docfx build -o "../publish"
 ```
-
-## Base host address
-
-By default, the navigation links will use the live site (<https://steeltoe.io>) as the base host address. You can override that by including the applicable metadata file.
-
-If running the MainSite locally on port 8080, then use the `localhost.json` metadata file.
-
-```powershell
-docfx build --serve --port 8082 --globalMetadataFiles "localhost.json" --logLevel Warning
+$ docker build -t docfx doxfx
 ```
 
-If running the MainSite locally with the dev site, then use the `devhost.json` metadata file.
+Sample invocation:
 
-```powershell
-docfx build --serve --port 8082 --globalMetadataFiles "devhost.json" --logLevel Warning
+```
+$ ./docfx.ps1 --version
+docfx 2.59.2.0
+Copyright (C) 2022 ? Microsoft Corporation. All rights reserved.
+This is open-source software under MIT License.
 ```
 
-## Updating Generated API Docs
+Download the 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 [docfx/docfx](docfx/docfx) for an example wrapper script.
 
-The contents of the folder `/api/(version)/all` was generated by running `docfx metadata` against the core Steeltoe codebase.
+Build API docs for Steeltoe 2 and 3
 
-## Running in Docker
+```
+$ 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
+```
 
-To test the documentation locally in Docker, run the following command:
+Build the site docs
 
-```bash
-docker-compose up
 ```
+# main site -> https://steeltoe.io
+$ docfx build --globalMetadataFiles main-site.json
 
-The main site will be serving at <http://localhost:9081> and the documentation site will be serving at <http://localhost:9082>.
-Note you can navigate from the navigation site to the documentation site using a browser.
+# main site -> https://dev.steeltoe.io
+$ docfx build --globalMetadataFiles main-site.dev.json
 
-## Contributions
+# main site -> http://localhost:9081
+$ docfx build --globalMetadataFiles main-site.localhost.json
+```
 
-All project information is available on the [Steeltoe Wiki](https://github.com/SteeltoeOSS/Steeltoe/wiki)
+Run local HTTP server
+
+```
+$ docfx serve _site -p 9082
+```

docfx.json

@@ -69,7 +69,7 @@
       }
     ],
     "xref": [
-      "build/_site/xrefmap.yml"
+      "_site/xrefmap.yml"
     ],
     "dest": "_site",
     "globalMetadataFiles": ["metadata.json"],

docfx.ps1

@@ -0,0 +1,3 @@
+#!/usr/bin/env pwsh
+
+Invoke-Expression "docker run -it --rm --volume $(Get-Location):/work docfx $args"

docfx/Dockerfile

@@ -1,11 +1,25 @@
 FROM mono:6.12
+WORKDIR /scratch
 RUN \
     apt-get update && \
     apt-get install -y \
         git \
         unzip \
+        vim \
         wget
-COPY . /work
 RUN \
-    /work/install.sh && \
-    rm -rf /work
+    wget https://packages.microsoft.com/config/debian/$(cat /etc/issue | awk '{print $3}')/packages-microsoft-prod.deb -O packages-microsoft-prod.deb && \
+    dpkg -i packages-microsoft-prod.deb && \
+    rm packages-microsoft-prod.deb && \
+    apt-get update && \
+    apt install -y \
+    dotnet-sdk-6.0
+COPY . .
+RUN \
+    wget https://github.com/dotnet/docfx/releases/download/$(cat docfx_version)/docfx.zip && \
+    mkdir -p /usr/local/libexec && \
+    unzip docfx.zip -d /usr/local/libexec/docfx && \
+    install docfx /usr/local/bin && \
+    rm -rf /scratch
+WORKDIR /work
+ENTRYPOINT ["docfx"]

docfx/docfx

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+mono /usr/local/libexec/docfx/docfx.exe $*

docfx/docfx_version

@@ -0,0 +1 @@
+v2.59.2

docker-compose.yaml

@@ -1,7 +1,7 @@
 version: "3"
 services:
-  mainsite:
-    image: steeltoe.azurecr.io/mainsite
+  main-site:
+    image: steeltoe.azurecr.io/main-site
     ports:
     - "9081:80"
     environment:

main-site.dev.json

@@ -0,0 +1,3 @@
+{
+  "_rootHost": "https://dev.steeltoe.io"
+}

main-site.localhost.json

@@ -0,0 +1,3 @@
+{
+  "_rootHost": "http://localhost:9081"
+}