Skip to content

Commit

Permalink
Update local build instructions and README
Browse files Browse the repository at this point in the history
* remove details of DocFX configuration; defer to DocFX docs
* rename main site configuration files to be main-site*.json
* provide a local Docker image to run DocFX as a convenience
  • Loading branch information
ccheetham committed Jun 6, 2022
1 parent 86f6dcb commit 45f3e08
Show file tree
Hide file tree
Showing 12 changed files with 91 additions and 94 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
/api/browser/**/*.manifest
/api/browser/**/*.yml
/obj/
/build/
/sources/
/_site/
/tools/
/.vscode/
/.vs/
Expand Down
127 changes: 58 additions & 69 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
---
Expand All @@ -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
```
2 changes: 1 addition & 1 deletion docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
}
],
"xref": [
"build/_site/xrefmap.yml"
"_site/xrefmap.yml"
],
"dest": "_site",
"globalMetadataFiles": ["metadata.json"],
Expand Down
3 changes: 3 additions & 0 deletions docfx.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#!/usr/bin/env pwsh

Invoke-Expression "docker run -it --rm --volume $(Get-Location):/work docfx $args"
20 changes: 17 additions & 3 deletions docfx/Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
3 changes: 3 additions & 0 deletions docfx/docfx
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#!/bin/sh

mono /usr/local/libexec/docfx/docfx.exe $*
File renamed without changes.
18 changes: 0 additions & 18 deletions docfx/install.sh

This file was deleted.

4 changes: 2 additions & 2 deletions docker-compose.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
3 changes: 3 additions & 0 deletions main-site.dev.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"_rootHost": "https://dev.steeltoe.io"
}
File renamed without changes.
3 changes: 3 additions & 0 deletions main-site.localhost.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"_rootHost": "http://localhost:9081"
}

0 comments on commit 45f3e08

Please sign in to comment.