statiqdev/statiq.docs

A static documentation site generator.

Statiq Docs

Statiq Docs is a flexible documentation generator. It’s built on top of Statiq Web and Statiq Framework so you can always extend or customize it.

📖 Read the documentation for updated quick start instructions as well as a more detailed guide.

💬 Use the Discussions repo for assistance, questions, and general discussion about all Statiq projects.

🐞 File an issue if you find a bug or have a feature request related to Statiq Docs.

💙 Support the project if you find Statiq useful or need to purchase a private license.

Licensing

Statiq Web is dual-licensed under a public license (which is an open license such as MIT that limits commercial use to fewer than 10 total individuals working as employees and independent contractors and less than 100,000 USD total revenue in the prior tax year) and a private license (which is an open license such as MIT with additional limits on assignment and sublicensing).

Please see the licensing FAQs for more information.

statiq.docs's Issues

Nested types don't seem to actually be listed anywhere

It seems that nested classes don't actually get listed anywhere. Even if they aren't listed in the Class Types list in the sidebar, they should be listed as members of the outer type. The only way I've currently found to get to them is to use the search.

Source files are ignored by generator

Not sure what is going on here. I've tried a bunch of different configurations and can't get anything to work.

I followed the steps here.

Then I clone my project into the src folder.

git clone [email protected]:rhys-vdw/peachy-tween.git src

Now, if I run the project I get errors because it's trying to include the source folder, so I edit my csproj to look like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- added these -->
    <Content Remove="src\**" />
    <Compile Remove="src\**" />
    <EmbeddedResource Remove="src\**" />
    <None Remove="src\**" />
    <!-- end-->
    <PackageReference Include="Statiq.Docs" Version="1.0.0-beta.5" />
  </ItemGroup>

</Project>

And when I run the output folder contains only sitemap.xml

[INFO] -> Code/Input » Starting Code Input phase execution... (0 input document(s), 1 module(s))

Namespace API docs show nested namespaces multiple times - once for each project they are in

A minor docs generation bug:

• I'm giving Wyam a Visual Studio solution containing 3 projects which all reference the same file containing all my namespace comments.
• The root API page looks fine.
• But the page for a specific namespace lists all of its nested namespaces once per project in the Namespaces section at the bottom.
• I've mostly worked around it by putting each of the namespace comments in #ifs so they only get included in one specific project, but one of my nested namespaces has classes in two of the projects so it still shows up twice in the list.

As a guess, the namespace list probably just needs a simple check for if an item already exists which wouldn't be necessary for anything else since namespaces are the only thing that can go across multiple assemblies.

Add xrefs for all API symbols

Including overloads, properties, etc. so you can xref to any symbol. See if the name should match what DocFx does for consistency.

Documentation error with nested namespaces

I have a file with comments for my namespaces like so:

/// <summary>The outer namespace.</summary>
namespace Outer { }

/// <summary>The inner namespace.</summary>
namespace Outer.Inner { }

That generated correct documentation for Outer.Inner but the summary of Outer combined the comments into "The outer namespace.The inner namespace".

Changing the namespaces to actually be nested fixed the problem though:

/// <summary>The outer namespace.</summary>
namespace Outer
{
    /// <summary>The inner namespace.</summary>
    namespace Inner { }
}

Make sure to escape all non-path chars in symbol names for docs

When figuring out the link path for symbols, make sure to escape all non-path chars since symbol names can include a pretty big set of chars

Verify doc comments specification

Make sure we're covering everything in https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md

Material theme for docs

checkout this theme in MKDocs: http://squidfunk.github.io/mkdocs-material/getting-started/

Would be great if Wyam can also come with such a theme for docs.

Add support for langword

Can be used in XML comments:

<see langword="true"/>

Should do something with it, perhaps make bold or at least use code styling. Could also consider making a lookup table that links back to official language docs.

Docs linking see elements with non-documented symbols to root

The problem happens when there's a <see cref="..."/> element in the docs and the cref points to a symbol from the standard library or elsewhere that we might have imported but didn't specify as documentation output.

See https://github.com/Wyamio/Wyam/blob/e674d45e96867f3cd3764bf344f4de70a3f3a85f/src/extensions/Wyam.CodeAnalysis/Analysis/XmlDocumentationParser.cs#L716 - presumably the link is populated but is either and empty string or something like a / or ..

Feature Request: separate inherited members from new ones

Related to https://github.com/Wyamio/Wyam/issues/800

I like how the Unity documentation lists new members and then inherited members in a separate list. For example: https://docs.unity3d.com/ScriptReference/CapsuleCollider.html. This makes is easy to see what the current class is actually adding separately from what it inherits.

Deconflict output files for symbols differing only by case in docs

As pointed out by @vcsjones - given two symbols differing only by case, they probably get output to the same location:

using System;
namespace Frog {
public class C {
    public void M() {
    }
} }

namespace FROG {
public class C {
    public void M() {
    }
} }

Need to check for this and ensure output to different paths.

Feature Request: group method overloads on a single API page

Unity's documentation puts all the overloads of a single method on the same page so you can easily compare their parameters. For example, GUI.Label.

Not needing a separate page for each overload might also make it possible to use member names as the page name instead of a GUID. I recently had one of those GUIDs change and break a couple of links from other pages (possibly due to removing the event keyword from the field?), which wouldn't have happened if I could just link to the member name.

Inheritance Diagram Drag Issues

I just grabbed Wyam v2.2.4. The panning and zooming in the API inheritance diagrams works nicely, but there are a couple of minor issues:

• It eats clicks of any mouse button, including middle click and buttons 4 and 5 which are used to navigate forward and back. Edit: it doesn't intercept buttons 4 and 5 in Firefox, only Chrome.
• If your mouse leaves the diagram, it stops dragging even if you keep holding the mouse button.
• There doesn't seem to be a boundary on how far you can move. Not really a problem with the Reset button, but could still be improved.

C# abstract/override events show both the base and override version in the child class

I have a public abstract event System.Action OnEnd in a base class and public override event Action OnEnd; in a child class, and the generated documentation for the child class lists both versions of the event: https://animancer.github.io/api/Animancer/ClipState/.

The default Samson theme for docs cuts off some of the text with the foldout arrow when it's expanded

Γhemes

Add support for automatically linking symbols

Leverages statiqdev/Statiq.Web#986 - also make it optional with a setting.

Enum Docs sort members by name rather than by value

I think it would be nicer to sort enums by their value rather than their name, though some might disagree. Perhaps a config option?

AddAssemblyFiles to populate "API"?

Good day

This is more of a question than an issue - but does Statiq.Docs support populating the "API" section using assemblies (with, or without the xml document files)?

I have a working sample which populates the API section using *.cs files in a "src" folder - that works without any issue. What I'm trying to do is get the same result but not using cs files, but the compiled dlls - is this possible?

I have a "assemblies" folder which contain the dll's at the same level as the "src" and "input" folders, and have added the following to program.cs (following this guide ) but it doesn't seem to do anything with the dlls (or the accompanying XML documentation files)

.AddAssemblyFiles("assemblies/**/*.dll")

Am I on the right track, or am I completely misunderstanding the guide?

Thanks in advance, appreciate it.

JP

Constructors only need to list parameters

There's no point in repeating the type name on every line when it's obviously going to be the same for every constructor. I recommend changing the heading to "Parameters" so in that image it would just show AnimancerState, Action<AnimationEvent>. That might even free up enough room to include the parameter names.

The implementation of https://github.com/Wyamio/Wyam/issues/800 might also influence the way this should be handled.

Docs search breaks on digits

See cake-build/website#494

Feature Request: add the ability to open documentation locally

Being able to freely host on sites like github is great, but sometimes it might be nice to be able to deliver the documentation along with the product without needing to host it online.

I'm not sure what the specific problem is, but from looking at the page when I try to open it locally it looks like it's just that the links are wrong for a set of local files.

Would it be feasible to either:

• A) add a wrapper of some sort that allows the site to be opened from local files.
• B) add an option to generate all links appropriately for local files instead of for a site that expects to be hosted.

Generic types should be sorted by parameter count rather than their names

In the class list, StateMachine<TKey, TState> gets put before StateMachine<TState> simply because K comes before S.

I think it would be better to sort generic types (any generic members really) by their parameter count.

GetTypeLink fails for tuples

I think there needs to be a special case. Once it gets into the if (typeArguments?.Count > 0) branch this succeeds, but then it fails with a "count can't be negative" error because the display name is something like (string Left, string Center, string Separator, string Right) after looking for the < and > in the type name rather than Tuple<string, string, string, string>

Active class in table header rows

I was trying out categories, but it seems that the table header row is getting a class of "active" and this is causing the background to be set to gray instead of the default themed color.

This is basically the default wyam new -r Docs.

At the very least, I'd like to know where this is coming from so that I can override it. Has anybody seen this?

Thanks

XML Exception tags get ignored

E.g.

/// <summary>...</summary>
/// <exception cref="NullReferenceException">Thrown if ...</exception>

This makes Visual Studio show the exception at the bottom of the tooltip, but Wyam doesn't do anything with it. I figure it just needs an "Exceptions" section at the bottom of the member's page.

Referencing a VS project lists it as an assembly instead of listing the name of its actual output DLL

I have two separate projects (Animancer.Editor and Animancer.Runtime) which both output different versions of Animancer.dll so that Unity can use one in the editor and the other in runtime builds.

Pointing Wyam to the Animancer.Editor project causes the API documentation to list Animancer.Editor.dll as the assembly instead of just Animancer.dll. In my case since I've made a separate copy of the project for Wyam I can just rename it, but it seems like a bug.

Also, I don't even really want it to list that assembly since I'm releasing my product as source code that gets compiled as part of the user's Unity project rather than as a pre-compiled DLL, so Animancer.dll will never actually exist for most users. It's not particularly important though, so I wouldn't want you to waste much time on it if it's not something simple to change.

XML references to long method signatures easily overflow the table

I have a method which ends up with a particularly long documentation signature even though it only has 3 parameters:

Animancer.AnimancerPlayable.GetOrCreateState(System.Object,UnityEngine.AnimationClip,System.Int32)

So when Wyam puts a reference to it in the table and doesn't allow such references to word wrap, it ends up giving the table a horizontal scroll bar which makes it really hard to use (about half of every line is hidden):

Allowing it to word wrap on non-alphanumeric characters like dots and brackets instead of only whitespace would probably be an acceptable solution, though I don't know how easily the word wrapping algorithm can be changed. Perhaps there's an invisible 0 width character that gets treated as whitespace which you could insert at relevant points in the code block?

It would be awesome if the text could just be AnimancerPlayable.GetOrCreateState(object,AnimationClip,int) (without the class prefix if we're currently looking at members inside that class) and have a tooltip with the fully qualified signature that shows up when you hover over it. A tooltip wouldn't even be necessary if it just generated a link to that method (which now that I think about it is probably a bug).

Also, relating to https://github.com/Wyamio/Wyam/issues/799, it's using the full type names of int and object here instead of their keywords.

Docs recipe blog archive links don't work

The Archive links in the sidebar of my blog don't work, presumably because they contain spaces: https://animancer.github.io/blog/.

API changes don't cause a rebuild while using the --watch command

Changing an input file while using the --watch command causes it to automatically rebuild the site, but changing a source file in the referenced C# project does not. It would be nice if it did, but I'm not sure how straightforward it would be to get the paths of the source files from the project to watch them as well. It's easy enough to work around though.

Also, even when it does get rebuilt, auto links don't seem to account for changes to the API:

1. Run Wyam with --watch and keep it running.
2. Add a class called MyClass.
3. Put a reference to MyClass in any of the input files where it would normally get auto-linked to that class in the API docs.
4. Change something in an input file to cause a rebuild.
5. That reference doesn't get auto-linked even though the new API page does exist.
6. Close Wyam and restart it.
7. Now it does get auto-linked properly.

Again, this is really minor and might not even be worth fixing because presumably it would mean spending more time rebuilding whatever cache the auto-linking system uses every time.

Feature Request: auto links to external documentation

It would be awesome if my documentation could automatically create links to external documentation just like it does to the pages generated for my API. For example, in a Unity project when I write GameObject in a markdown file I'd like it to link to https://docs.unity3d.com/ScriptReference/GameObject.html.

This could have two parts:

• First you'd specify "here's a website to check for documentation". Or maybe "if the class is in this DLL, check this website".
• Then it would likely also be good to have the ability to manually specify specific pages. So that Animation Events could link to https://docs.unity3d.com/Manual/animeditor-AnimationEvents.html without needing to put that link in everywhere.

Maybe it could use a "LinkResolver" text file that specifies the exact token -> URL pairings so it doesn't need to ping the target website every time to make sure it exists, it just writes into that file the first time. And so you can manually specify and alter the links in one central location.

This might be something that could be done with a custom pipeline (or module?), but I have no idea how to take the regular default pipeline and insert an extra step for modifying the output generated by code tags.

Support for Markdown format

Microsoft has started to embed <format type="text/markdown"> into their XML docs and DocFx knows how to render it. It would be great if we could too and make this something of a conventional standard. Will need to do a little research to make sure the semantics and usage match.

Struct syntax shows unnecessary inheritance from ValueType

Feature Request: allow docs auto-links for Attribute classes without the suffix

C# allows you to make a class like public class TooltipAttribute : Attribute and then apply it to something using [Tooltip] without the word "Attribute" on the end.

It would be nice if Wyam could auto generate links to the API documentation of that class when using code tags around [Tooltip] and Tooltip like it does for the full TooltipAttribute.

API Layout Suggestion: put "Syntax" at the top

It seems to me that the syntax is even more important than the summary so it should go right under the member heading.

And the Assembly/Namespace/ContainingType should be moved a bit out of the way such as in the top right or even the top left where it already shows the containing type. That section is obviously pretty important for types because it has the inheritance diagram, but for individual members it's always just those 3 things and you usually already know roughly where you are. They could even be shown on a single line at the top: Assembly.dll -> Namespace.ContainingType.

Also, I believe C# actually calls it the "Declaring Type" rather than "Containing Type".

Use short names if possible when documenting <see> tags

If I'm already on the page for Animancer.AnimationEventReceiver, it doesn't really need to use the full name when referring to members in that type.

The summary in that image could just be "Constructs a new AnimationEventReceiver and sets the Source and Callback."

API Derived Types list isn't sorted

Protected internal members don't get documented

protected internal members aren't listed in the API documentation even though they are visible to inheriting types just like regular protected members (as well as to everything in the assembly like internal).

References to a protected internal field such as the _BasePlayable in the Remarks of my AnimancerState link to the root of the site, though presumably that's only because the member didn't get a page of its own.

<seealso> tags don't link to the specified member

/// <summary>
/// The best field ever.
/// <seealso cref="SomeMethod"/>
/// </summary>
/// <seealso cref="AnotherMethod"/>
public float value;

This produces an API page with a See Also section listing both SomeMethod and AnotherMethod, but they are just plain text when I would have expected links to their respective pages.

PS: is it still worth posting bug reports in this repo or has the code base of Statiq diverged so much that things like this could be fixed and/or completely different anyway?

Getting incorrect output from references to certain generic methods

I have a few XML comments with <see> tags that are generating incorrect output:

<see cref="Array.Resize"/> is generating System.Array.Resize``1(``0[]@,System.Int32)

and <see cref="List{T}.Sort(Comparison{T})"/> is generating

System.Collections.Generic.List`1.Sort(System.Comparison{`0})

Add the props file from Statiq.Web to Statiq.Docs

It does not appear to be restoring transitively and instead of spending hours debugging that behavior it's probably easier to just copy over the props file into the Statiq.Docs package

C# XML Doc element `include` is not part of generated documentation

Hi,
I'm trying out Wyam for documenting a C# code base and in the code there is a case where xml doc comments are shared across a few (similiar) classes using the include xml doc element, documented here; https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#include

However, when using Wyam with the Docs recipe the contents of these referenced xml files are not included in the Wyam generated docs site. I tried to point to my AssemblyFiles instead of the SourceFiiles, but then I end up with no API item in the main menu at all. I'm not sure if I'm doing it right;

Settings[DocsKeys.AssemblyFiles] = "src/**/obj/Debug/**/*.dll";
Settings[DocsKeys.SourceFiles] = null;

For the assembly that has these doc comments with include elemnets, msbuild also produces an .xml file on the form AssemblyName.xml in the same folder as the .csproj file. This xml file does include the docs referenced from the include elements, ie repeated for each time it is referenced.

I'm thinking maybe that file is of interest and in the Wyam docs for the "Docs" recipe it says that features of the recipe includes:

API documentation from assemblies (with or without XML documentation file from MSBuild).
(https://wyam.io/recipes/docs/overview)

Could someone clarify how to make use of that generated XML documentation as input for Wyam generation?

Nested types cause URL conflicts for Docs recipe

When using the Docs recipe on an code base with nested types there can be name conflicts.

For example when running the recipe against this code:

namespace Demo
{
    public class Temperature
    {
        public enum Mode { Hot, Cold }
    }

    public class Orientation
    {
        public enum Mode { North, South }
    }
}

It produces this error:

Multiple documents output to api/Demo/Mode/index.html (this probably wasn't intended):
  Demo.Orientation.Mode
  Demo.Temperature.Mode

Operators don't get fully documented

Implicit operators (possibly other operators too) like the one below are listed in the API documentation, but they don't get their own page like other functions and their summary column is always empty.

/// <summary>Best comment ever.</summary>
public static implicit operator MyClass(string path)
{
    return new MyClass(path);
}

Shortcodes/XML processing instructions escaped when code is on the page in docs recipe

Essentially makes shortcodes impossible to use on a page with either code fences or inline backticks

Docs Recipe - no setting for includeProtected (AnalyzeCSharp.WherePublic)

Wyam.Docs.Pipelines.Api.GetModules() calls AnalyzeCSharp.WherePublic() which by default includes protected. It would be nice to be able to configure this so you can exclude protected methods/properties from the documentation..

<see> tags in XML comments don't generate the correct HTML links when inside a <list>

/// <summary>
/// This reference works: <see cref="AnotherThing "/> 
/// <list type="bullet">
///   <item>
///   But this one doesn't: <see cref="AnotherThing "/> 
///   </item>
/// </list>
/// </summary>
public class Thing { }

public class AnotherThing { }

Feature Request: support XML <include> tags

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/include

The documentation doesn't explain what referencing project and solution files actually does

It would help new users if https://wyam.io/recipes/docs/settings explained what DocsKeys.ProjectFiles and DocsKeys.SolutionFiles actually affect.

API documentation writes Object in upper case instead of using the lowercase keyword

Other types like float use their lowercase keywords instead of the actual type name System.Single but object doesn't.