search

statiqdev / Statiq.Docs

A static documentation site generator.
https://statiq.dev/docs
Other
53 stars 8 forks source link

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

Open SilentSin opened 6 years ago

SilentSin commented 6 years ago

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

SilentSin commented 6 years ago

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

Do they affect the generated output directly or something else?

SilentSin commented 6 years ago

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 commented 6 years ago

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.