API Documentation

[JoshClose]

I'm writing an API documentation generator. It's currently using NuDoq to parse the assembly.

What would be the best way to inject this into Static.Web processing? It will be generating content, metadata, and possibly more.

There are no input files needed. It will just need to read some config values, like where to find the assembly it's generating the docs from.

[daveaglick]

Cool! Just FYI, Statiq will eventually have in-the-box API documentation support via Statiq Docs but I'm all about keeping stuff open so lots of different techniques can be used as needed (just wanted to make sure you knew it was coming).

My first instinct would be to add the NuDoq code to a module and then add that module to a new pipeline (let's call it Api). Then add the Api pipeline as a dependency of the Input pipeline:

.ModifyPipeline(nameof(Pipelines.Inputs), x => x.Dependencies.Add(nameof(Api)))

You could have the module generate a document-per-symbol, or maybe a document-per-class. Then, since it's a dependency of the Inputs pipeline you can iterate over those documents in other pages and layouts or create archives from them.

Does that make sense for a starting point?

[bjorkstromm]

Can you point me to an example on what DocFX does? It's probably like you say, if DocFX does it, it shouldn't be a problem for Statiq either.

[daveaglick]

There's actually a standard for these files. Basically you stick the same XML doc comments you'd add to the symbol in a stand-alone XML file and then use <include> to reference them: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/include. Wyam used to support this (though there were some problems and I think it might have gotten dropped at some point) and I've got every intention of Statiq supporting it.

[JoshClose]

When the C# compiler sees the tag, it searches for documentation comments in xml_include_tag.doc instead of the current source file.

I just tried with a <summary> in source and all the <param>s in an include file and the xml file that was built contained both. It seems to be merging them. I'll probably continue to put most of the docs in code, then larger blocks like <example> could go in another file.

I believe this also means there is no extra work on your part. It's just built in.

Make sure to handle user defined tags when parsing the docs also.

This doc has a much better example. https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#include

[daveaglick]

I believe this also means there is no extra work on your part. It's just built in.

I wish! :)

The XML documentation support is...interesting. Roslyn (which is what Statiq generally uses under the hood for code analysis) supports most of the conventions and standards that are detailed in the MS docs, but not necessarily out of the box. A few of the features like these external XML files require a little extra handholding and configuration. And on top of that, Visual Studio gets fancy with some of the more exotic pseudo-standards. For example, ever noticed that <inheritdoc> works in Visual Studio? That's not actually part of Roslyn but something Visual Studio added on top of it.

[JoshClose]

<include> also works with in VS which is nice.

I guess I assumed you would be opening the Library.xml file that is generated and using that.