What rules apply to the SHFB IntelliSenseComponent output folder?

Question

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

Fortunately, Sandbule Help File Builder has its own build component - IntelliSenseComponent - which is exactly the right thing ... in theory. Unfortunately, I cannot figure out how to properly configure it.

The documentation provides an example:

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

and conditions:

The above example is taken from the Builder Builder Sandcastle configuration file. When used with it, the replacement tags {@SHFBFolder} and {@OutputFolder} are used to insert the help file creation folder and the project output folder in the file path. They are replaced during assembly with the corresponding values. If you use the component in your own build scripts, replace the tags with the relative or absolute path to the component build and output folder, respectively.

Well, I use SHFB, so I expect this to work. However, I cannot get anything but the absolute path to work. I tried:

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

(I just use XYZZY as what is easy to find.)

Looking at the source code , I was hoping I could use an environment variable, but that didn't work:

 folder="%CD%\XYZZY" 

although it is ...

 folder="%USERPROFILE%\XYZZY" 

It works:

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

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

The documentation suggests that all this should be very simple ... what am I missing?

Used Versions:

• SHFB: 1.9.3.0
• Sandcastle: 2.6.10621.1

Answer 1

My experiments showed that the SHFB IntelliSenseComponent was right about {@OutputFolder} , but there is a nuance.

If the folder attribute specified in

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

points to the folder inside the OutputPath project OutputPath ( .\docs\api in your case), then the SHFB build process creates the folder and then deletes it before creating the contents of the website:

 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 {@OutputFolder} exactly the same as the value of $(OutputPath) , so if you put something like {@OutputFolder}\foo in the folder attribute, you will never see foo after completion assembly.

The solution is simple: specify a folder located outside the project output folder, for example:

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

Hope this helps.