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.
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.
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.
InstallHead over to the Wyam GitHub page and check out the latest releases. You have a couple options.
- You can download a self contained zip file that has the Wyam.exe
- 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 CodeBy 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 DocsFrom 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 docsThe
-rdocs 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.
BuildingWe’re ready to build our static API docs already. I know, not much setup required!
> .\Wyam.exe buildThis 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 WebserverNow this feature is pretty cool. You can preview and use your browser to view your docs by using the preview command.
> .\Wyam.exe previewNow if we head over to our browser and head over to http://localhost:5080 we get our awesome looking API docs!