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

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

43 голосов
/ 16 февраля 2012

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

К счастью, Конструктор файлов справки Sandcastle имеет пользовательский компонент сборки - 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, что легко найти.)

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

folder="%CD%\XYZZY"

хотя это было ... 

folder="%USERPROFILE%\XYZZY"

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

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

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

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

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

  • SHFB: 1.9.3.0
  • Замок из песка: 2.6.10621.1

1 Ответ

44 голосов
/ 17 февраля 2012

Мои эксперименты показали, что IntelliSenseComponent SHFB правильно обработал {@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" />
<!--                            ^^       -->

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

...