Trying to get started with documentation based on c# project

[paulvanbladel]

Very cool project, but very difficult to get your head around the basics for using it :)

Trying to get a starting point for creating a simple (but custom) documentation system over a c# project.
So, to focus the ideas, let's say i just want to enumerate all classes in a project together with it's xml summary comment and the full namespace of the class.
I'm perfectly capable doing this with Roslyn, but I do not understand the magic of statiq "AnalyseCSharp".
So, i'm starting with:

internal class Program
{
    public static async Task<int> Main(string[] args) => 
        await Bootstrapper
                .Factory.CreateDefault(args)
                .BuildPipeline("Analyse Code", 
                    builder => builder
                        .WithInputModules(new ReadProject("path to .csproj"))
                        .WithProcessModules(new AnalyzeCSharp())
                        .WithProcessModules(new MyModule())
                    )
                .RunAsync();
}

Is there no sample project available somewhere which can give me some pointers to get a simple boilerplate of this working?
Help would be very much appreciated.
Kind regards

[daveaglick]

Have you seen Statiq Docs? Statiq Framework (which is the code you've got above) is more of a "toolkit" and like most very complex frameworks, can take a bit of a learning curve. There are two projects that sit on top of that to make things easier: Statiq Web which is intended to make simple web sites, blogs, etc. and Statiq Docs which is intended to create documentation sites. Both of those higher-level projects take a lot of work out of setting up a Statiq Framework from scratch and reduce it to one or two lines of code.

That said, a lot of the core functionality of those higher-level projects (though not all) does reside in Statiq Framework and you can still use it directly if you want. A great example of this is the Spectre.Console documentation site. It uses Statiq Framework directly to deliver a very customized documentation experience. You can see where it's calling the AnalyzeCSharp module in a pipeline here: https://github.com/spectreconsole/spectre.console/blob/main/docs/src/Pipelines/CodePipeline.cs.

As with most frameworks, understanding the core concepts is also helpful. Just like it would difficult to understand how ASPNET Core works without first understanding things like dependency injection and web routing, Statiq is based on a few core ideas like documents and metadata. If you haven't done so already, I'd recommend reading the section on those concepts here: https://www.statiq.dev/guide/documents-and-metadata/.

The job of the AnalyzeCSharp module is to take some input code (whether that's a project file, assembly, or raw source files), run Roslyn on it, and then convert it to documents that represent each symbol. Those documents contain metadata with the various properties of the symbol. You can see the available metadata here: https://github.com/statiqdev/Statiq.Framework/blob/main/src/extensions/Statiq.CodeAnalysis/AnalyzeCSharp.cs (though you can also use the Symbol metadata to get the raw Roslyn symbol instance that each document is based on).

Working on more examples, themes, documentation, and the general user experience is a big goal of mine for 2024. At the moment, while Statiq is still in beta, the focus is on improving reliability, performance, and functionality - but once 1.0 is released, which I'm hoping to do early this year, that focus will shift. In the meantime, going outside the pre-canned conventions and functionality of Statiq Web and Statiq Docs does require a bit of spelunking to understand how it all fits.

[daveaglick]

To expand just a bit on the relationship between AnalyzeCSharp and documents/metadata - the AnalyzeCSharp module outputs documents. Then those documents need to be processed/iterated in some way. The general pattern for this is to use the AnalyzeCSharp module in a pipeline that isn't intended to output anything to disk, just to gather documents-per-symbol. Then in a second pipeline that has that first pipeline as a dependency, use Razor (or similar) to access the documents representing symbols from the first pipeline and iterate/display/whatever them.

[paulvanbladel]

Many thanks Dave for your reply, I will study the referenced material in detail. Very much appreciated.

[daveaglick]

No problem! And I or other users are around for more detailed questions as they come up too (I can't promise a speedy response, though I'm trying to get to things a little faster).