Branding and initial docs site (#2)

* Branding of VSTeam docs site
* auto-generating documentation from vsteam module
* created pipeline for automated deployment

Co-authored-by: Sebastian S Schütze <[email protected]>

Author: SebastianSchuetze

.gitignore

@@ -19,4 +19,6 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-docs/modules/**/*-*md
+modules/vsteam/**/*-*.md
+modules/vsteam/**/sidebars.js
+modules/**/index.md

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "svg.preview.background": "black",
+    "files.associations": {
+        "*.yml": "azure-pipelines"
+    }
+}

README.md

@@ -2,8 +2,16 @@
 
 This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
 
+### Module documentation
+
+Part of the documentation is not saved in the repository.
+Especially the module documentation is generated on the fly by downloading the modules and generating the markdown files with [platyPS](https://github.com/PowerShell/platyPS).
+Building of these files is integrated with the `yarn start` and `yarn build` commands.
+
 ### Installation
 
+Install all dependencies
+
 ```
 $ yarn
 ```
@@ -31,3 +39,7 @@ $ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+### Limitations
+
+When using `yarn start` the module markdown is only generated once and not updating automatically. It only watches changed files which are part of the documentation.

azure-pipelines.yml

@@ -1,10 +1,4 @@
 parameters:
-  - name: BuildFrom
-    type: string
-    default: Module
-    values:
-      - Markdown
-      - Module
   - name: Deploy
     type: boolean
     default: true
@@ -13,55 +7,38 @@ trigger:
   - master
 
 pool:
-  vmImage: 'windows-latest'
+  vmImage: 'ubuntu-latest'
 
-resources:
-  repositories:
-    - repository: github_vsteam
-      type: github
-      name: "MethodsAndPractices/vsteam"
-      endpoint: VS-TeamPipelines
-
-steps:
-  - checkout: self
-    persistCredentials: true
-  - checkout: github_vsteam
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '10.x'
-    displayName: 'Install Node.js'
-
-  - ${{ if eq(parameters.BuildFrom, 'Markdown') }}:
-    - task: PowerShell@2
-      displayName: 'Build VSTeam Module Help - From Markdown'
-      inputs:
-        targetType: 'inline'
-        script: |
-          .\vsteam-docs\tools\ci\Create-VSTeamHelp.ps1 -Path ".\vsteam\.docs" -Destination ".\vsteam-docs\docs\module-vsteam"
-
-  - ${{ if eq(parameters.BuildFrom, 'Module') }}:
-    - task: PowerShell@2
-      displayName: 'Build VSTeam Module Help - From Module'
-      inputs:
-        filePath: '$(System.DefaultWorkingDirectory)/vsteam-docs/tools/ci/Build-VSTeamModuleHelp.ps1'
-  - script: |
-      cd vsteam-docs/website
-      yarn install
-      yarn run build
-    displayName: 'docs build'
-
-  - ${{ if eq(parameters.Deploy, true)}}:
-    - script: |
-        git config --global user.name "${GH_NAME}"
-        git config --global user.email "${GH_EMAIL}"
-        echo "machine github.com login ${GH_LOGIN} password ${GH_TOKEN}" > ~/.netrc
-        git checkout master
-        cd vsteam-docs
-        yarn install
-        GIT_USER="${GH_LOGIN}" CURRENT_BRANCH=master yarn run deploy
-      env:
-        GH_NAME: $(GH_NAME)
-        GH_LOGIN: $(GH_LOGIN)
-        GH_EMAIL: $(GH_EMAIL)
-        GH_TOKEN: $(GH_TOKEN)
-      displayName: 'docs deploy'
+stages:
+  - stage: build
+    displayName: Build
+    jobs:
+    - job: test_build
+      displayName: Check Build
+      steps:
+        - template: ./tools/ci/azurepipelines/buildDocs.yml
+  - stage: deploy
+    displayName: Deploy GitHub Pages
+    condition: and(succeeded(), and(eq(variables['System.PullRequest.IsFork'], false), eq(variables['Build.SourceBranch'],'refs/heads/master')))
+    jobs:
+    - deployment: Deploy
+      displayName: Deploy Docs
+      environment: GitHub Pages VSTeam Docs
+      strategy:
+        runOnce:
+          deploy:
+            steps:
+            - template: ./tools/ci/azurepipelines/buildDocs.yml
+            - script: |
+                git config --global user.name "${GH_NAME}"
+                git config --global user.email "${GH_EMAIL}"
+                echo "machine github.com login ${GH_LOGIN} password ${GH_TOKEN}" > ~/.netrc
+                git checkout master
+                yarn install
+                GIT_USER="${GH_LOGIN}" CURRENT_BRANCH=master yarn run deploy
+              env:
+                GH_NAME: $(GH_NAME)
+                GH_LOGIN: $(GH_LOGIN)
+                GH_EMAIL: $(GH_EMAIL)
+                GH_TOKEN: $(GH_TOKEN)
+              displayName: 'docs deploy'