diff --git a/.gitignore b/.gitignore index f1bb3075..baba4906 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,8 @@ /api/browser/**/*.manifest /api/browser/**/*.yml /obj/ -/build/ /sources/ +/_site/ /tools/ /.vscode/ /.vs/ diff --git a/README.md b/README.md index 14b5b28d..b981b102 100644 --- a/README.md +++ b/README.md @@ -2,33 +2,26 @@ ## 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 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. -If you are using VS Code as your editor, there is a [super sweet plugin for docfx](https://marketplace.visualstudio.com/items?itemName=tintoy.docfx-assistant). All it really does is discover `UID`'s and provide intellisense with the `@` char is typed in markdown. +## Directories -Also 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` | documentation Markdown and Table of Contents +| `/api/v2` | version 2 documentation +| `/api/v3` | version 3 documentation +| `/articles` | blog post Markdown +| `/images` | images +| `/template` | theming -## Folders +## DocFX Markdown -- /api: holds the project documentation markdown and table of contents - - /v2: version 2 documentation - - /v3: version 3 documentation -- /apidoc: in the future this will hold generated api docs from src -- /articles: holds the markdown for blog posts -- /images: the images -- /template/steeltoe: odd files that overwrite the default docfx theme - -## Markdown parser - -Docfx offers a custom flavor of markdown with quite a few enhanced capabilities. To see examples and learn more, view the [docfx specifications](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 pages `UID`. With this you can create `xref` as well as use docfx's `@` shorthand. Lean more about [linking in docfx](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). **Note** it should be very rare that you hard code a link to an 'html' page with your markdown. Instead use it's `UID` and let the path get calculated as well links get 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. 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. 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: @@ -51,10 +44,10 @@ author.twitter: thebigguy Let's talk about something really cool... ``` -## Creating a new api document +## 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 examples below that the `topicHref` are not absolute paths. Docfx will calculate everything at build time. -An example api doc: +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: ```markdown --- @@ -70,77 +63,73 @@ Or you could link to the v3 version of this doc: @api/v3/circuitbreaker/hystrix Or do the same thing by provide custom link text: [view the v3 version](xref:api/v2/circuitbreaker/hystrix) ``` -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 temp folder named `_site` and be served at http://localhost:8080. +### 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 +## Building the site -The contents of the folder `/api/browser` was generated by running `docfx metadata` against the core Steeltoe codebase. To generate/test this locally, run the following command: +Build API docs for Steeltoe 2 and 3 -## Running in Docker +``` +$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v3 -b release/3.2 +$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v2 -b release/2.5 +$ git clean -fX api +$ docfx metadata api-v3.json +$ docfx metadata api-v2.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 +``` + +Run local HTTP server -All project information is available on the [Steeltoe Wiki](https://github.com/SteeltoeOSS/Steeltoe/wiki) +``` +$ docfx serve _site -p 9082 +``` diff --git a/docfx.json b/docfx.json index 065d59ba..5208d150 100644 --- a/docfx.json +++ b/docfx.json @@ -69,7 +69,7 @@ } ], "xref": [ - "build/_site/xrefmap.yml" + "_site/xrefmap.yml" ], "dest": "_site", "globalMetadataFiles": ["metadata.json"], diff --git a/docfx.ps1 b/docfx.ps1 new file mode 100755 index 00000000..d8a814d9 --- /dev/null +++ b/docfx.ps1 @@ -0,0 +1,3 @@ +#!/usr/bin/env pwsh + +Invoke-Expression "docker run -it --rm --volume $(Get-Location):/work docfx $args" diff --git a/docfx/Dockerfile b/docfx/Dockerfile index 41fad485..5cd6ae8d 100644 --- a/docfx/Dockerfile +++ b/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 && \ + cp docfx /usr/local/bin && \ + rm -rf /scratch +WORKDIR /work +ENTRYPOINT ["docfx"] diff --git a/docfx/docfx b/docfx/docfx new file mode 100755 index 00000000..e59cae6a --- /dev/null +++ b/docfx/docfx @@ -0,0 +1,3 @@ +#!/bin/sh + +mono /usr/local/libexec/docfx/docfx.exe $* diff --git a/docfx/version b/docfx/docfx_version similarity index 100% rename from docfx/version rename to docfx/docfx_version diff --git a/docfx/install.sh b/docfx/install.sh deleted file mode 100755 index 0d3ad96d..00000000 --- a/docfx/install.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env bash - -set -e - -cd "$(dirname "${BASH_SOURCE[0]}")" - -version=$(cat version) -wget https://github.com/dotnet/docfx/releases/download/${version}/docfx.zip -mkdir -p /usr/local/libexec -unzip docfx.zip -d /usr/local/libexec/docfx -rm docfx.zip - -cat </usr/local/bin/docfx -#!/bin/sh -mono /usr/local/libexec/docfx/docfx.exe \$* -EOF - -chmod +x /usr/local/bin/docfx diff --git a/docker-compose.yaml b/docker-compose.yaml index 8927dd25..459f25bc 100644 --- a/docker-compose.yaml +++ b/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: diff --git a/main-site.dev.json b/main-site.dev.json new file mode 100644 index 00000000..16bbcf3c --- /dev/null +++ b/main-site.dev.json @@ -0,0 +1,3 @@ +{ + "_rootHost": "https://dev.steeltoe.io" +} diff --git a/host.json b/main-site.json similarity index 100% rename from host.json rename to main-site.json diff --git a/main-site.localhost.json b/main-site.localhost.json new file mode 100644 index 00000000..0bdc7fa2 --- /dev/null +++ b/main-site.localhost.json @@ -0,0 +1,3 @@ +{ + "_rootHost": "http://localhost:9081" +}