Streamline Deploying your documentation with DocFx 2, DotNet 5, and Docker

At the time of writing this DocFx is not playing well DotNet (.NET) 5 Projects. The error specifically is reading .csproj and .sln files to get the API documentation, or your 3 slash code comments. This presented me with a slight problem, and here was my solution.

I was needing to publish my documentation for a work project since we just upgraded to .NET 5. So I first was working on running Docfx with Mono inside a docker container it took me a few minutes to get that running after getting that to successful work I came across the bug between .NET 5 & Docfx, noted here: Github. So you just have to build your code, let docfx read those .dll files, then finally deploy to a web server for view.

To achieve this I built a 3 stage docker file to get the documentation built you can see an example of the Dockerfile below.

# build .dll files for docfx to inspect
FROM AS code-env


COPY . .

RUN dotnet publish -o ./.build src/FileShare.API

# build docs with docfx using mono
FROM mono as docs-env

RUN apt update && apt install -y unzip wget

WORKDIR /tools

RUN wget

RUN unzip -d ./docfx

WORKDIR /build

COPY --from=code-env /app/.build .build

COPY . .

RUN mono /tools/docfx/docfx.exe build docfx_project/docfx.json

# deploy using nginx for static file hosting
FROM nginx:latest

WORKDIR /var/www/html

COPY --from=docs-env /build/docfx_project/_site .

WORKDIR /etc/nginx/conf.d

COPY ./docfx_project/default.conf default.conf

Why I use Docker for documentation deployment

I have used docker deploying services for some time now. I like that there is no configuring the service on a server, or a developer on another team, can pull it and run it locally, so they have access offline. It also integrates well in my build pipeline.

Leave a Reply