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

[SilentSin]

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

[SilentSin]

It also isn't really clear what #a directives are supposed to do.

Do they affect the generated output directly or something else?

[SilentSin]

If I reference a solution do I need to reference its projects as well?

Which build configuration will it use from the solution - debug or release? The first one? Whichever is currently selected in Visual Studio?

[daveaglick]

Great questions

It also isn't really clear what #a directives are supposed to do

#a adds an assembly to the references for the config file. For example, if you wanted to read JSON code inside your configuration file and had a local copy of Newtonsoft you wanted to reference. #a does not impact your documentation or load assemblies for analysis in the docs.

If I reference a solution do I need to reference its projects as well?

You shouldn’t need to - using a solution for docs should document all the projects in that solution. Let me know if you find otherwise.

Which build configuration will it use from the solution - debug or release?

It’ll do whatever’s defined in the project file as the default, essentially it runs dotnet build proj.csproj (or msbuild proj.csproj) for each project in the solution. It doesn’t do any further solution parsing like figuring out VS build configurations.