Generate C# API Documentation with Wyam

Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.

Learn more about Software Architecture & Design.
Join thousands of developers getting weekly updates to increase your understanding of software architecture and design concepts.

Leave this field empty if you're human:

We’ve all ran into the situation of wanting or needing to create API documentation.  It could be your open source library/framework or for your internal work projects.

Wyam

Wyam is a highly modular and extremely configurable static content generator and toolkit.

It can be used for all sorts of things like creating a blog, but one of cool things it can do is build some awesome API documentation for your C# code. So if you are in the market for generating API docs, check this out.

Install

Head over to the Wyam GitHub page and check out the latest releases.  You have a couple options.

1. You can download a self contained zip file that has the Wyam.exe
2. Download the Setup.exe installer

Note:  You may also need to right-click the zip file after download and select “Unblock” in the Security section of the properties dialog, otherwise you could get strange errors when using the application.

For this demo I’m going with the zip file.  Simply unzip and call the Wyam.exe CLI from PowerShell.

> .\Wyam.exe help

Source Code

By convention, we can put our source code for our project we want to create API docs for in the src/ folder. I cloned the Nancy repo into the src folder so we can generate API docs for it.

New Docs

From the screenshot above, we can tell from the help options that we can call the Wyam CLI with a “new” command.  In order to generate docs, we can call.

> .\Wyam.exe new -r docs

The -r docs argument is to specify that we are using the “docs” recipe.  As mentioned you can also create other types of static content such as a blog using the blog recipe.

Building

We’re ready to build our static API docs already.  I know, not much setup required!

> .\Wyam.exe build

This process may take some time to build all the fields depending on the size of your project. You should now have an output/ directory that contains all of your static content (html files) for your docs.

Preview with Built-in Webserver

Now this feature is pretty cool.  You can preview and use your browser to view your docs by using the preview command.

> .\Wyam.exe preview

Now if we head over to our browser and head over to http://localhost:5080 we get our awesome looking API docs!

More

There is a ton you can do with Wyam.  One aspect I find really interesting is being able to embed with the NuGet package Wyam.Core.  I plan on exploring that option more and will likely have more posts about Wyam soon. Are you using a static site generator for API docs?  If so, I’d love to hear your comments below or via Twitter