Gautam Kumar

Data Scientist

Every company at some point in time does repetitive work. That’s a good thing. But if the process is not well documented, it would lead to breakdowns in the future. These breakdowns are not good for the clients and the business as a whole. Therefore, the documentation process should be given as much importance as we give to the development process. So lets startof with brief introduction about DocFX, GitHub and DevOps

DocFX is an API documentation generator for .NET, which currently supports C#, VB, and F#. It generates API reference documentation from triple-slash comments in your source code. Here is the link to get started https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

GitHub is a US-based global company that provides hosting for software development version control using Git. It is a subsidiary of Microsoft, which acquired the company in 2018. Here is the link to get started https://github.com/

Azure DevOps Server is a Microsoft product that provides version control, reporting, requirements management, project management, automated builds, lab management, testing and release management capabilities. It covers the entire application lifecycle, and enables DevOps capabilities. Here is the link to get started https://azure.microsoft.com/en-in/services/devops/

Let us now start off with the integration of DocFx with GitHub and Azure DevOps:

Step 1: Install DocFX using one of the following methods:

  • Chocolateychoco install docfx -y.
  • Homebrew (owned by community): brew 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 anywhere.
  • NuGetnuget install docfx.consoledocfx.exe is under folder docfx.console/tools/.

Step 2: Create a sample project using:

docfx init -q

Step 3: Build the website using:

docfx docfx_project\docfx.json --serve

You can view the website on http://localhost:8080.

Step 4: Create a folder named scripts at the project root as shown in the figure

Step 5: Add the following script (name: build.sh) in the scripts folder

brew update && brew install azure-cli

echo "Logging in to Azure"
az login --service-principal -u $AZUREAPPID -p $AZUREAPPKEY --tenant $AZUREAPPTENANT

mkdir $BUILD_SOURCESDIRECTORY/_dl
mkdir $BUILD_SOURCESDIRECTORY/_bin
mkdir $BUILD_SOURCESDIRECTORY/_publish

wget -O $BUILD_SOURCESDIRECTORY/_dl/docfx.zip "https://github.com/dotnet/docfx/releases/download/v2.37/docfx.zip"
unzip $BUILD_SOURCESDIRECTORY/_dl/docfx.zip -d
$BUILD_SOURCESDIRECTORY/_bin/docfx

cd $BUILD_SOURCESDIRECTORY/$DOCSFOLDER
mono $BUILD_SOURCESDIRECTORY/_bin/docfx/docfx.exe
cp -R $BUILD_SOURCESDIRECTORY/$DOCSFOLDER/_site/. $BUILD_SOURCESDIRECTORY/_publish/

az storage blob upload-batch -s $BUILD_SOURCESDIRECTORY/_publish -d \$web --account-name $AZURESTORAGE

Step: 6 Push your code to your GitHub repository

Link to Part-2

Link to Part-3

Categories:

  • Azure
  • Engineering
  • Integrations
Recommended Articles:
Contact Us