Статья:
Sandcastle — Новый генератор документации для .NET

Автор(ы): Никита Зимин
Дата: 23.11.2006
Sandcastle — проект, цель которого — предоставить разработчикам библиотек классов по всему миру средство простого создания точной и информативной документации общепринятого вида.

Авторы:
Никита Зимин

Аннотация:
Sandcastle — проект, цель которого — предоставить разработчикам библиотек классов по всему миру средство простого создания точной и информативной документации общепринятого вида.

НЗ>Статья:
НЗ>Sandcastle — Новый генератор документации для .NET

Автор(ы): Никита Зимин
Дата: 23.11.2006
Sandcastle — проект, цель которого — предоставить разработчикам библиотек классов по всему миру средство простого создания точной и информативной документации общепринятого вида.

Еще в ходе написания статьи многие хотели посмотреть на пример — как процесс выглядит в натуре и каков результат.

http://rsdn.ru/File/10885/TestSandcastle.zip

• test.cs — исходный файл примера из папки Sandcastle: Examples\Sandcastle\test.cs
  
• test.dll — скомпилированный пример
  
• comments.xml — файл XML-комментариев, полученный при компиляции
  
• doc.build — скрипт сборки для NAnt
  
• go.bat — командник для запуска doc.build под NAnt

Использование:

1. Распаковываем в какую-нибудь папку на диске
   
2. Настраиваем пути в doc.build
   
3. Запускаем: go build
   В результате в папке "C:\Program Files\Sandcastle\Examples\My" создается структура каталогов HTML-файлы и другие файлы, приготовленные для сборки справки. Сборка идет в эту папку для того, чтобы не возиться с путями в файлах Sandcastle.config.
   
4. Запускаем go build-chm
   В результате получаем файл "C:\Program Files\Sandcastle\Examples\My\Output\test.chm".
   Примечание: описанный в статье инвертор для hhc.exe я не ставил, поэтому результат сборки всегда будет FAILED.

Параметр var.Presentation в doc.build задает используемый шаблон.

Для совсем ленивых — в тот же архиве лежат готовые .chm, сделанные на разных шаблонах:

• test-Prototype.chm
  
• test-vs2005.chm

Задался вопросом — а как бы мне получить с помощью Sandcastle документацию на русском? Т.е. чтобы весь шаблон документации был русифицирован. Оказалось, всё не просто, а очень просто. И в этом смысле Sandcastle намного превосходит NDoc.

В папке Sandcastle\Presentation делаем копию папки vs2005 под именем vs2005ru. В новом шаблоне, в папке Content переводим содержимое трёх небольших XML-файлов на русский, считая что эти файлы записаны в UTF-8. В Configuration\sandcastle.config заменяем имя папки vs2005 на vs2005ru. В copyOutput.bat делаем то же самое.

Теперь можем в нашем процессе сборки

Автор: nzeemin
Дата: 02.12.06

поставить в качестве имени шаблона vs2005ru и прогнать процесс создания HTML-файлов.

Есть, правда, и ложка дёгтя. ReflectionToChmContents.xsl и ReflectionToChmIndex.xsl не работают, поскольку пытаются записать кириллицу в кодировку Latin-1. А значит, .chm-файл нам не получить. Написал им на форум. Будем посмотреть…

На случай если кому интересно поэкспериментировать — положил частично переведённые XML-файлы тут:
http://rsdn.ru/File/10885/vs2005ru_Draft.zip

Здравствуйте, nzeemin, Вы писали:

N>Есть, правда, и ложка дёгтя. ReflectionToChmContents.xsl и ReflectionToChmIndex.xsl не работают, поскольку пытаются записать кириллицу в кодировку Latin-1. А значит, .chm-файл нам не получить. Написал им на форум. Будем посмотреть…

Достаточно там прописать вместо latin-1 UTF8 и все работает.

Здравствуйте, Аноним, Вы писали:

А>Достаточно там прописать вместо latin-1 UTF8 и все работает.

Не все так просто.
Процесс завершится без ошибок, но в результате мы получим .CHM с кракозяблами в содержании.

Собственно, вот проверенная рецептура:

1. Изменения в ReflectionToChmContents.xsl (REFLECTIONTOCHMCONTENTS.XSL.BAK — исходная версия файла):

***** ReflectionToChmContents.xsl

        <xsl:output method="text" encoding="windows-1251" />

***** REFLECTIONTOCHMCONTENTS.XSL.BAK

        <xsl:output method="text" encoding="iso-8859-1" />

*****

2. Аналогичные изменения нужно сделать и в ReflectionToChmIndex.xsl

3. Изменения в ReflectionToChmProject.xsl:

***** ReflectionToChmProject.xsl
                <!-- <xsl:text>Display compile progress=No
</xsl:text> -->
                <xsl:text>Language=0x419 Russian
</xsl:text>

***** REFLECTIONTOCHMPROJECT.XSL.BAK
                <!-- <xsl:text>Display compile progress=No
</xsl:text> -->
                <xsl:text>Language=0x409 English (United States)
</xsl:text>

*****

Здравствуйте, Никита Зимин, Вы писали:

Важное отличие этого процесса от процесса NDoc: в Sandcastle основой всегда является сборка, на основе мета-информации сборки строится весь справочник, файл XML-комментариев является необязательным;

Но тем не менее при добавлении сборки в список необходимо указывать и имя XML файла. Без него не добавляется. Если указать неверный XML, то при билде ошибка
BUILD FAILED: Unable to find XML comments file: Unknown.xml

Здравствуйте, Аноним, Вы писали:

А>Здравствуйте, Никита Зимин, Вы писали:

А>

А>Важное отличие этого процесса от процесса NDoc: в Sandcastle основой всегда является сборка, на основе мета-информации сборки строится весь справочник, файл XML-комментариев является необязательным;

Опять же непонятно, если инфа берется из сборки, то зачем вручную указывать папку с Dependences? Без указания опять ошибка, что не найдены внешние сборки.
Кстати, возможно ли генерить доки только из основной сборки, не затрагивая остальное ?

Здравствуйте, Никита Зимин, Вы писали:

А не подскажете, как в коде программы можно указывать summary для namespace? В частности в NDoc для этого заводился класс NamespaceDoc, и его summary использовался в качестве summary для namespace.

Здравствуйте, Никита Зимин, Вы писали:

НЗ>Аннотация:
НЗ>Sandcastle — проект, цель которого — предоставить разработчикам библиотек классов по всему миру средство простого создания точной и информативной документации общепринятого вида.

Опечатка.
вместо ключа

/internal:+

должно быть

/internal+