Source files are ignored by generator

[rhys-vdw]

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 git@github.com: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))

[rhys-vdw]

Also I've had no luck adding files from other locations using AddProjectFiles or AddSourceFiles... I'm completely confused. It would be nice if there was a way to add a project file explicitly, rather than with a glob so that it could error out when the file is missing.

[markashleybell]

Same here I'm afraid. I've followed exactly the same path as @rhys-vdw describes above, but no matter what I do, no code is ever processed by the pipeline.

I'm always seeing the Starting Code Input phase execution... (0 input document(s) messaging when I run it, and no output:

I've tried using the conventional relative src paths (both at the level above the docs folder and also within it), and also all of the methods described here to explicitly add code; I've tried those with both relative and absolute paths specified.

It feels like I'm doing something silly, but I can't figure out what that might be, or find any extra clues in the documentation.

Here's the very minimal example repo I've been testing against, in case it either helps, or allows someone to point out my mistake(s):

https://github.com/markashleybell/statiqdocsspike

[markashleybell]

Ah! Some luck! I think the issue is because the default glob pattern doesn't quite match up with the folder conventions in the docs?

There are obviously some other issues with e.g. absolute paths not working, but adding an extra ../ to the start of the default glob pattern resulted in my pipeline successfully finding the sources:

See here: https://github.com/markashleybell/statiqdocsspike/commit/2243460360a6930d24730080f28a5f0dff915a55

[rhys-vdw]

I ended up moving to DocFX so I have no more insight into this.

[daveaglick]

Sorry for the long delay here folks, I've had a number of personal reasons why this project has had to take a backseat for me for a bit but hopefully moving past that soon.

@rhys-vdw Hopefully DocFx is working well for you - it's a good project.

@markashleybell Thanks a lot for exploring this issue a bit more. I still need to dig deeper - there are plenty of folks using Statiq Docs out of the box without problems so I'd like to understand where the differences lie. I suspect, as you did, that there might be some inconsistencies with the Statiq guides and the explanations of where to place files.

[markashleybell]

@daveaglick You're welcome, and thank you for all your hard work on this project—I do understand how much effort is involved in something like this, and it's very much appreciated.

Whenever you have some time, do you have a few examples of projects where this is working out of the box please?

I've tried a search on GitHub for Statiq.Docs usage, but the results are a bit overwhelming to comb through... I did find this project, but actually in their settings they are doing the same thing I've done, i.e. adding an extra ../ to the start of the source file. And it seems like all of the others I can initially find are also explicitly passing in paths.

Given a couple of comparisons, I'm happy to try and figure out what I'm doing wrong/differently which is causing my problems, and maybe put in a PR with some tweaks/additions to the docs?

[nils-a]

@markashleybell I stumbled across this issue:

You're missing the Docable theme in the ./docs/theme folder. See Docable#installation on options how to add it.

[markashleybell]

@nils-a Thanks, but unless I'm missing something—which is certainly possible!—I don't think that would be the cause of this particular issue.

The problem is that the generator wasn't finding my C# source files in order to generate API documentation for them—nothing to do with theming, as far as I can see.

It might well have confused me later though, so thank you for pointing it out!

[nils-a]

@markashleybell Ah. Maybe I misinterpreted, then. I thought that you still had the problem of not seeing the generated api-doc.

[daveaglick]

@markashleybell Thanks again for the reproduceable spike. I finally dedicated some time to figuring out what's going on here, and I think you nailed it with

actually in their settings they are doing the same thing I've done, i.e. adding an extra ../ to the start of the source file

It appears that one of the problems in creating a tool for developers is that they'll happily just go off and hack it if it doesn't work quite right - so all this time I never realized the default paths weren't working as intended out of the box (since I too set custom paths).

More specifically, the way the path is used is in a ReadFiles module like this:

new ReadFiles(
    Config.FromSettings(settings
        => settings.GetList<string>(DocsKeys.SourceFiles).AsEnumerable())));

And the ReadFiles module is rooted at the input folder, so the intent is definitely not to pull in source files from inside the input folder, that would lead to all kinds of silliness. I think we need to crawl up one for src folders alongside the input folder (I.e. in the same project/folder structure) and then also up another for src folders alongside the Statiq project as in your spike. I'm going to go ahead and make that change now and it'll go out with the next release.

[markashleybell]

@daveaglick That's great, glad you were able to get to the bottom of it!