What rules are applied to SHFB's IntelliSenseComponent's output folder?

Question

Noda Time has an issue against it that the XML documentation file it ships contains all the internal and private members too - which is a shame.

Fortunately, Sandcastle Help File Builder has a custom build component - IntelliSenseComponent - which does exactly the right thing... in theory. Unfortunately, I can't work out how on earth to configure it properly.

The documentation gives this example:

 <output includeNamespaces="false" namespacesFile="Namespaces"
   folder="{@OutputFolder}" />

and states:

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, the replacement tags {@SHFBFolder} and {@OutputFolder} are used to insert the help file builder's folder and the project's output folder in the file paths. These are replaced at build time with the appropriate values. If using the component in your own build scripts, replace the tags with a relative or absolute path to the component assembly and output folder respectively.

Well, I am using SHFB, so I'd expect that to work. However, I can't get anything other than an absolute path to work. I've tried:

folder="."
folder="{@OutputFolder}"
folder="{@OutputFolder}XYZZY"
folder="{@OutputFolder}\XYZZY"
folder="{@OutputFolder}/XYZZY"
folder="{@OutputFolder}/XYZZY/"

(I'm just using XYZZY as something that's easy to search for.)

Looking at the source code, I'd hoped that I could use an environment variable, but this didn't work:

folder="%CD%\XYZZY"

although this did...

folder="%USERPROFILE%\XYZZY"

This works:

folder="c:\users\jon\test\xyzzy"

... but I really don't want an absolute path-name there.

The documentation suggests that all of this should be really easy... what am I missing?

Versions involved:

SHFB: 1.9.3.0
Sandcastle: 2.6.10621.1

folder="%CD%\XYZZY" doesn't work because %CD% is not expanded by Environment.ExpandEnvironmentVariables which IntelliSenseComponent uses. I believe it can be expanded by cmd.exe only (just like %TIME%, %CMDCMDLINE%, etc.) — Igor Korkhov

Igor Korkhov Igor Korkhov · Accepted Answer · 2012-02-17T13:26:51

My experiments showed that SHFB's IntelliSenseComponent did treat {@OutputFolder} correctly, but there's a nuance.

If the folder attribute specified in

<output includeNamespaces="false" namespacesFile="Namespaces"
        folder="..." />

points to a folder inside a project's OutputPath folder (.\docs\api in your case) then SHFB's build process creates the folder, but then deletes it before generating website contents:

Last step completed in 00:00:34.5875
-------------------------------
Combining conceptual and API intermediate TOC files...

Clearing any prior web output
    Last step completed in 00:00:00.2360
-------------------------------
Extracting HTML info for HTML Help 1 and/or website...

The problem is that the default value of the {@OutputFolder} is exactly the same as the value of $(OutputPath), therefore if you put something like {@OutputFolder}\foo in the folder attribute then you'll never see foo after build has finished.

The solution is simple: specify a folder that is located outside of your project's output folder, like this:

<output includeNamespaces="false" namespacesFile="Namespaces"
        folder="{@OutputFolder}\..\distilledApi" />
<!--                            ^^       -->

Hope this helps.

What rules are applied to SHFB's IntelliSenseComponent's output folder?

1 Answers