Ответ 1
Я не уверен, какие инструменты Apple использует внутри. Поскольку у меня была такая же потребность, я поделюсь тем, что узнал, и тем, что я закончил.
Два из моих проектов с открытым исходным кодом требовали "очень качественной" документации, которая идеально была бы неотличима от документации, предоставленной Apple. Эти два проекта:
RegexKit стал первым проектом. Я искал что-то, что угодно, чтобы помочь с документацией. Единственными инструментами, которые, казалось бы, были проблемы: Doxygen и, судя по всему, инструмент, поставляемый с Xcode: HeaderDoc. Имейте в виду, что это было несколько лет назад, поэтому ситуация, вероятно, немного изменилась.
Существующие инструменты
Doxygen используется множеством проектов, но мне никогда не нравился стиль, который он генерирует. Не говоря уже о том, что это не было похоже на документацию на яблоки, и из того, что я мог сказать, заставить ее генерировать то, что я действительно хотел, было просто непрактично.
Первоначально HeaderDoc выглядел многообещающим. Фактически, некоторые файлы заголовков фреймворков включают HeaderDoc разметку, например:
/System/Library/Frameworks/CoreFoundation.framework/Headers/CFArray.h
Быстро стало очевидно, что HeaderDoc просто не собирается его сокращать. Это было медленно, очень медленно, и его вывод HTML был по существу "установлен в камне" - например, не было системы шаблонов. Что бы вы ни выбрали, задним концом является то, за чем вы застряли, за исключением некоторых незначительных изменений, которые вы можете сделать с таблицами стилей CSS.
RegexKit Решение
Итак, что делать? Поскольку я уже отметил некоторые заголовки, используя HeaderDoc, я решил опрокинуть свои собственные. Все это часть дистрибутива, если вы хотите взглянуть на него. Это определенно показывает его родословную, хотя: начался как быстрый хак, который только продолжал расти и расти. Не красиво, не нужно понимать, не говоря уже о модифицированном или даже используемом кем-либо еще. Это по существу полная система документации: она анализирует файлы заголовков, извлекает не только разметку HeaderDoc, а фактический исходный код, который помечен как Что ж. Вся эта необработанная информация сбрасывается в базу данных sqlite, а затем script генерирует окончательный вывод HTML. Поскольку все сначала анализируется, ссылки между заголовками (для классов, типов и т.д.) Не представляют проблемы. Он также позволяет автоматически создавать оглавление.
С небольшим усилием в настройке одиночных пиксельных расстояний через таблицу стилей CSS она (или, по крайней мере, была в то время) идеальной эмуляцией HTML-документации, поставляемой Apple. Стиль документации яблок немного изменился для iPhone/10.6, но он все еще очень близок.
Не только это почти идентично документации HTML, большое количество усилий было сделано в специальной таблице стилей печати, так что, если вы распечатаете документацию из браузера, особенно Safari, она выглядит почти идентично Apples PDF документация... особенно если у вас есть правильные шрифты - Palatino и Letter Gothic. Поскольку Safari, очевидно, настроен для вывода на экран, а не на выходе принтера, он будет выполнять разрывы страниц в неудобных местах... но это определенно проходимо. Нулевые изменения в HTML, все это сделано автоматически с изменением таблицы стилей CSS.
Когда я начал, Mac OS X 10.5 еще не был выпущен. С 10.5 появился DocSet, который позволяет тесно интегрировать документацию в редактор Xcode. Поскольку все было забито в базу данных sqlite, потребовалось всего несколько дней для создания необходимых файлов XML, необходимых инструментам DocSet. Несмотря на то, что для создания системы документации было много дополнительной работы, я смог интегрировать всю документацию непосредственно в Xcode всего за несколько дней, сделав это стоящим.
RegexKitLite Решение
RegexKitLite пришел позже, и, как вы можете догадаться из "Lite", он должен быть меньше. Я хотел всего лишь один HTML файл для всего. Я начал работу с шаблонами и стилями CSS, выполненными для RegexKitи построил HTML файл "вручную", ничего автоматизированного для него. Даже файлы XML, необходимые для DocSet, были засеяны разделенными версиями из RegexKit, а затем редактировались вручную.
Если вы не можете найти решение и вам нужно сворачивать самостоятельно, я настоятельно рекомендую вам взять копию RegexKitLite HTML и использовать его в качестве плиты котла. Документация распространяется на одну и ту же лицензию BSD, но вы можете обходить содержимое и использовать оставшийся скелет в качестве шаблона без атрибуции.
Так как RegexKitLite является "более новым" из двух, он получил наибольшую любовь. Я знаю, что его таблица стилей CSS намного лучше и имеет множество улучшений по сравнению с тем, что я начал с RegexKit. Кроме того, вы можете просто вырвать весь материал JavaScript <script>, поскольку его единственная цель - позволить вам выделить/выделить регулярное выражение в документе, а затем выполнить некоторое автоматическое выражение regex → NSString при копировании /Command -C в Safari.
Идеальное решение... или то, что я хочу на Рождество.
Мое идеальное решение было бы простой в использовании разметкой. В конце концов, мне не понравился стиль разметки HeaderDoc. Определенно нужно быть гибким и расширяемым пользователем, а также ориентироваться на шаблоны. HTML, и особенно XML, - это способ, на мой взгляд. Я думаю, что я предпочел бы нечто большее, чем Markdown или reStructuredText, но, очевидно, изменен для этой задачи. В частности, было бы неплохо иметь кратковременную разметку для ссылок на такие вещи, как другие классы, типы и т.д., А шаблон/бэкэнд автоматически переписывает его в целевой формат вывода, скажем, HTML, и автоматически гиперссылки на ссылку для вас по мере необходимости.
Для высококачественной печатной продукции вы наверняка собираетесь использовать TeX, LaTeX или одну из своих производных. Мне еще не пришлось широко использовать *TeX, но он предназначен для публикации книг и печатных изданий. Также довольно тривиально создавать очень качественные "диаграммы" всего за несколько десятков строк текста. Для HTML вы в значительной степени застреваете в создании растрового изображения с помощью другой цепочки инструментов (photoshop? Visio? И т.д.).
Кроме того, я хотел бы просто кусать пулю и полностью перемещаться в цепочку инструментов *TeX и генерировать HTML из источников .tex. Однако каждый раз, когда я пытался, я просто был перегружен. Это невероятно мощный инструмент, а .tex источник/разметка не так уж плох... но обучение достаточно, чтобы настроить вещи, чтобы получить точный стиль вывода, который я хочу... ну, давайте так выразиться. *TeX был создан Дональдом Кнутом, известность The Art of Computer Programming, потому что, когда он писал писать свои книги, требующие очень качественного набора математических формул, он был недоволен существующими решениями. Поэтому он провел несколько лет и написал свой собственный. Он был на краю современного компьютерного набора и типографии, а также из-за его созданных фрагментов в процессе.
