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

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

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

В документации приведен пример:

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

и состояния:

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

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

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

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

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

folder="%CD%\XYZZY"

хотя это...

folder="%USERPROFILE%\XYZZY"

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

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

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

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

Используемые версии:

SHFB: 1.9.3.0
Sandcastle: 2.6.10621.1

Ответ 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" />
<!--                            ^^       -->

Надеюсь, что это поможет.