Add docfx and initial docs skeleton (microsoft#141)

.github/workflows/docfx_build.yml

@@ -0,0 +1,48 @@
+name: DocFX Build
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build:
+    name: Build
+    runs-on: windows-latest
+    steps:
+      # Check out the branch that triggered this workflow to the 'source' subdirectory
+      - name: Checkout Code
+        uses: actions/checkout@v2
+        with:
+          path: source
+      # Run a build
+      - name: Build docs
+        run: "& ./eng/common/build.ps1 -restore -build -projects ./docs/docfx/docfx.csproj"
+        working-directory: ./source
+      # Check out gh-pages branch to the 'docs' subdirectory
+      - name: Checkout docs
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+          path: docs
+      # Sync the site
+      - name: Clear docs repo
+        run: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ }
+        working-directory: ./docs
+      - name: Sync new content
+        run: Copy-Item -Recurse -Verbose -Force "$env:GITHUB_WORKSPACE/source/docs/docfx/_site/*" .
+        working-directory: ./docs
+      # Commit
+      - name: Commit to gh-pages and push
+        run: |
+          $ErrorActionPreference = "Continue"
+          git add -A
+          git diff HEAD --exit-code
+          if ($LASTEXITCODE -eq 0) {
+            Write-Host "No changes to commit!"
+          } else {
+            git config --global user.name "$env:GITHUB_ACTOR"
+            git config --global user.email "$env:[email protected]"
+            git commit -m"Updated docs from commit $env:GITHUB_SHA on $env:GITHUB_REF"
+            git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+            git push origin gh-pages
+          }
+        working-directory: ./docs

docs/README.md

@@ -0,0 +1,7 @@
+# Docs Folder
+
+This folder contains:
+
+* [Design Notes](designs/) - These are the design notes used to guide our development. They aren't designed to be usage guides but may help contributors in understanding why some patterns were used.
+* [Operations](operations/) - These are operational docs for running releases and other infrastructure related to the project.
+* [Public Usage Docs](docfx/) - This is a [docfx](https://dotnet.github.com/docfx) project that generates our public docs site [microsoft.github.io/reverse-proxy](https://microsoft.github.io/reverse-proxy). Any commit to `master` will trigger the [GitHub Action](../.github/workflows/docfx_build.yml) to rebuild the docs site and push it to the `gh-pages` branch.

docs/docfx/.gitignore

@@ -0,0 +1,10 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
+log.txt

docs/docfx/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/docfx/api/index.md

@@ -0,0 +1,3 @@
+# API Documentation for YARP
+
+This is the API reference documentation for YARP.

docs/docfx/articles/index.md

@@ -0,0 +1,6 @@
+---
+uid: intro
+title: Welcome to the YARP documentation!
+---
+
+# Welcome to the docs

docs/docfx/articles/toc.yml

@@ -0,0 +1,2 @@
+- name: Tutorial
+  href: tutorial.md

docs/docfx/articles/tutorial.md

@@ -0,0 +1,8 @@
+---
+uid: tutorial
+title: Getting Started with YARP
+---
+
+# Tutorial: Getting Started with YARP
+
+TODO: Fill this in!

docs/docfx/docfx.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.Net.Sdk">
+    <!--
+        This is a project that is used to edit/maintain docs in VS and to build the actual docfx site
+    -->
+    <PropertyGroup>
+        <TargetFramework>netstandard2.0</TargetFramework>
+        <LogLevel>Info</LogLevel>
+
+        <!-- Doc build only supports Windows -->
+        <BuildDocFx Condition="'$(OS)' != 'Windows_NT'">false</BuildDocFx>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="docfx.console" Version="2.52.0" />
+    </ItemGroup>
+</Project>

docs/docfx/docfx.json

@@ -0,0 +1,68 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../../src",
+          "files": [
+            "**.csproj"
+          ]
+        }
+      ],
+      "dest": "api",
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/index.md"
+        ]
+      },
+      {
+        "files": [
+          "articles/**.md",
+          "articles/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "apidoc/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default"
+    ],
+    "postProcessors": [],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false,
+    "xrefService": [
+      "https://xref.docs.microsoft.com/query?uid={uid}"
+    ]
+  }
+}

docs/docfx/index.md

@@ -0,0 +1,10 @@
+---
+uid: root
+title: YARP Documentation
+---
+
+# YARP: A Reverse Proxy
+
+Welcome to the documentation for YARP! YARP is a high-performance, production-ready, reverse proxy written for .NET 5. Right now it's still in preview, but please provide us your feedback by going to [the GitHub repository](https://github.com/microsoft/reverse-proxy).
+
+For a brief getting started guide, see the [Tutorial](xref:tutorial).

docs/docfx/toc.yml

@@ -0,0 +1,8 @@
+- name: Home
+  href: index.md
+- name: Articles
+  href: articles/
+  homepage: articles/index.md
+- name: Api Documentation
+  href: api/
+  homepage: api/index.md

eng/Build.props

@@ -4,5 +4,6 @@
         <!-- Exclude samples, they aren't packable -->
         <ProjectToBuild Include="$(RepoRoot)src\**\*.csproj" />
         <ProjectToBuild Include="$(RepoRoot)test\**\*.csproj" />
+        <ProjectToBuild Include="$(RepoRoot)docs\docfx\docfx.csproj" Condition="'$(OS)' == 'Windows_NT'" />
     </ItemGroup>
 </Project>

reverse-proxy.sln

@@ -41,9 +41,8 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{6CBE18D4-64E9-492B-BB02-58CD57126C10}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{BC344A50-8F81-4762-9F4B-12714693144B}"
-	ProjectSection(SolutionItems) = preProject
-		docs\config.md = docs\config.md
-	EndProjectSection
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "docfx", "docs\docfx\docfx.csproj", "{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -149,6 +148,14 @@ Global
 		{11D098B2-7116-4F37-817A-E496B8F15C76}.Release|Any CPU.Build.0 = Release|Any CPU
 		{11D098B2-7116-4F37-817A-E496B8F15C76}.Release|x64.ActiveCfg = Release|Any CPU
 		{11D098B2-7116-4F37-817A-E496B8F15C76}.Release|x64.Build.0 = Release|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Debug|x64.Build.0 = Debug|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Release|x64.ActiveCfg = Release|Any CPU
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3}.Release|x64.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -166,6 +173,7 @@ Global
 		{8ECD71FA-3E74-4F4E-AE5D-0C4681F8A7B7} = {149C61A2-D9F8-49B9-9F9B-3C953FEF53AA}
 		{D294FD0A-CF8E-4DB2-B722-08577DB890D2} = {149C61A2-D9F8-49B9-9F9B-3C953FEF53AA}
 		{11D098B2-7116-4F37-817A-E496B8F15C76} = {149C61A2-D9F8-49B9-9F9B-3C953FEF53AA}
+		{7F6D4710-07D1-49D0-8EAE-675A3A9B50E3} = {BC344A50-8F81-4762-9F4B-12714693144B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {31F6924A-E427-4830-96E9-B47CEB7BFE78}