DocFx

The website is based on the OSS DocFx project. DocFx generates documentation directly from source code (.NET, RESTful API, JavaScript, Java, etc...) and Markdown files.

Markdown

Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

For a fast introduction on Markdown, take a look at the Markdown Cheatsheet.

Check the Markdown section for more details on the DocFx Flavored version.

Quick Start

Install DocFx

Install DocFx from one of the following sources:

• Chocolatey: choco install docfx
• GitHub: download and unzip docfx.zip from https://github.com/dotnet/docfx/releases. Extract it to a local folder, and add it to PATH so you can run it from anywhere.

Clone the DevOps OSB repository

To work locally, you need to retrieve the source code from Azure Devops.

git clone https://osbgroup.visualstudio.com/One%20Step%20Beyond/_git/DevOps%20OSB

How to update / create new content

To publish content to this site please follow below process.

Work items

All changes have to be linked to a work item. Either to a user story or to a task, depending on the complexity of the new / updated content. If it is a complex one with many changes, please create separate tasks to break down your work into smaller pieces.

Backlog is available in Azure DevOps.

Branching

Main branch is protected by branch policies and it can be updated only via pull requests, which must be approved at least one other team member. When a pull request is approved and merged into the main branch, new content will be deployed automatically to this site.

In order to create new content or update existing one you have to create a feature branch which is linked to the work item which you are currently working on. When you finished the task, commit and push your changes. It is a good habit to set the pull request to auto-complete and tick the checkboxes to delete the branch and complete the related work items.

Test your project locally

Before you create a pull request your changes have to be tested locally. In order to do that, fire up docfx server and validate whether the site can be built by docfx and also validate your changes visual appearance in your favorite browser.

Go to the \docfx folder and execute the following commands:

docfx build
docfx .\docfx.json --serve

You can now browse your local website on http://localhost:8080 with your preferred web browser.