Какие правила применяются к выходной папке SHFB IntelliSenseComponent?

Question

Noda Time имеет issue против него, что файл документации XML, который он отправляет, содержит также все внутренние и частные члены - что является позором.

К счастью, Sandcastle Help File Builder имеет пользовательский компонент сборки - IntelliSenseComponent - который делает именно то, что нужно ... в теории. К сожалению, я не могу понять, как правильно настроить его.

Документация дает этот пример:

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

и заявляет:

Приведенный выше пример взят из Sandcastle Файл справки файл конфигурации Строителя. При использовании с ним теги замены {@SHFBFolder} и {@OutputFolder} используются для вставки папки создателя файла справки и выходной папки проекта в пути к файлам. Они заменяются во время сборки соответствующими значениями. Если вы используете компонент в своих собственных скриптах сборки, замените теги на относительный или абсолютный путь к сборке компонентов и папке вывода соответственно.

Ну, я утра с помощью SHFB, так что я бы ожидать, что работать. Тем не менее, я не могу получить что-нибудь, кроме абсолютного пути к работе. Я пробовал:

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

(. Я просто использую XYZZY как то, что легко искать)

Глядя на source code, я надеялся, что я мог бы использовать переменную окружения, но это не сработало:

folder="%CD%\XYZZY" 

хотя это сделал ...

folder="%USERPROFILE%\XYZZY" 

Это работает:

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

... но я действительно не хочу здесь абсолютного пути.

Документация предполагает, что все это должно быть очень просто ... чего мне не хватает?

Версии, связанные:

• SHFB: 1.9.3.0
• Sandcastle: 2.6.10621.1

Answer 1

Мои эксперименты показали, что SHFB в IntelliSenseComponent сделал лакомство {@OutputFolder} правильно, но есть нюанс.

Если атрибут folder указан в

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

указывает на папку внутриOutputPath папке и проекта (.\docs\api в вашем случае), то процесс сборки SHFB создает папку, но затем удаляет его перед генерацией содержимого веб-сайта :

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... 

Проблема в том, что значение по умолчанию для {@OutputFolder} точно такое же, как и значение $(OutputPath), поэтому, если вы поместите что-то вроде {@OutputFolder}\foo в атрибут folder, тогда вы никогда не увидите foo после завершения сборки.

Решения просто: укажите папку, которая находится за пределы выходной папки вашего проекта, как это:

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

Надеется, что это помогает.