Statiq for code documentation

[bertiewooster]

Hello, I'd like to automatically document .NET code (C# and VB). Am I understanding correctly that the solution for that is Statiq.Docs, which is not yet ready for release? Is there an estimate or timeline for Statiq.Docs release? Thanks!

[daveaglick]

Yep, both correct. Statiq Docs is coming along nicely and I'm in (what I hope is) the final stage of porting over a theme that uses the code analysis data being generated to render a nice looking site. It's technically usable right now, but without a good theme as a starting point, it's not going to be of much use to anyone. Thankfully I'm not starting from scratch there as Statiq Docs works similar to and will look like the Wyam docs theme.

As for timing, I'm really not sure and I'm hesitant to predict anything because life happens and I might fall behind. That said, I think it's more on the order of months over years. Perhaps sometime in Q2 of this year (I.e. 2 - 4 months until a release).

[bertiewooster]

Any updates, @daveaglick? Thanks!

[daveaglick]

SO CLOSE!

It's usable now. I'm still working on guides, documentation, etc. so use at your own risk. I'll announce more broadly once I feel like there's enough documentation for folks to have a good onboarding process. There might be a few rough edges too, but some testing would be great anyway.

Quick start can be found here for now: https://github.com/statiqdev/statiqdev.github.io/blob/api/input/docs.md

And the theme you'll need to use is here: https://github.com/statiqdev/Docable

Until I get around to updating theme installation instructions in Docable, the instructions here work the same way: https://github.com/statiqdev/CleanBlog#installation

Hopefully that's all you need to get started. Here's what API docs look like:

[yankun]

HI, I'm having the issue that nothing is generated at all. I've followed the tutorial exactly. The console app is placed directly in a docs folder, my source resides in src:

repo
-src
-docs

But as Input Path(s) only theme/input and input are shown. Calling AddAssemblies() or AddSolutions() has no effect neither.
The Root path is exactly where I expect it to be.

I there any way to debug, why no source code is found?

[daveaglick]

There are a few diagnostic steps we can take. The first is to see if the generator is picking up on any source files at all. You should have a final "table" being output from the command line that looks kind of like this:

Number of output documents per pipeline and phase:

 | Pipeline          | Input         | Process        | PostProcess      | Output         | Total Time |
 |-----------------------------------------------------------------------------------------------------|
 | AnalyzeContent    | 5095 (3 ms)   |                |                  |                | 3 ms       |
 | Api               |               | 4969 (2617 ms) |                  |                | 2617 ms    |
 | Archives          |               | 21 (10063 ms)  | 21 (1751 ms)     | 21 (28 ms)     | 11842 ms   |
 | Assets            |               | 21 (546 ms)    |                  | 21 (35 ms)     | 581 ms     |
 | Code              | 789 (1683 ms) |                |                  |                | 1683 ms    |
 | Content           |               | 5053 (1897 ms) | 5053 (103155 ms) | 5053 (1712 ms) | 106764 ms  |
 | Data              |               | 0 (18 ms)      |                  | 0 (7 ms)       | 25 ms      |
 | DirectoryMetadata | 0 (277 ms)    | 0 (1 ms)       |                  |                | 278 ms     |
 | Feeds             |               | 2 (654 ms)     |                  | 2 (19 ms)      | 673 ms     |
 | Inputs            | 114 (306 ms)  | 114 (487 ms)   |                  |                | 793 ms     |
 | Redirects         |               | 0 (17 ms)      |                  | 0 (7 ms)       | 24 ms      |
 | SearchIndex       |               |                | 0 (0 ms)         | 0 (7 ms)       | 7 ms       |
 | Sitemap           |               |                | 1 (564 ms)       | 1 (117 ms)     | 681 ms     |

Can you paste in here what yours looks like? More specifically we're looking to see if the Api and/or Code pipelines output any documents in their input and process phases.

Another thing to try is to see if moving the src folder under the docs folder (alongside the docs\input folder) makes a difference. I'd be curious to know what the result of that is.

[markashleybell]

Hi—just to chime in, I'm having the same problem, as is another dev who created this issue:

statiqdev/Statiq.Docs#53

I've posted all the details there along with a minimal repo which reproduces the problem.