Я уверен, что они используют что-то действительно фантастическое для создания своих документов и руководств. Все настолько упорядочено и равномерно, и у них всегда есть HTML и PDF-версия. Теперь мы создаем большую структуру и хотим предоставить хорошую документацию, которая создала бы способ, которым это делает Apple. Онлайн в формате HTML и офлайн в формате PDF.
Любая идея, как это сделали люди Apple? Какие инструменты они используют?
Я не уверен, какие инструменты Apple использует внутри. Поскольку у меня была такая же потребность, я поделюсь тем, что узнал, и тем, что я закончил.
Два из моих проектов с открытым исходным кодом требовали "очень качественной" документации, которая идеально была бы неотличима от документации, предоставленной Apple. Эти два проекта:
RegexKit стал первым проектом. Я искал что-то, что угодно, чтобы помочь с документацией. Единственными инструментами, которые, казалось бы, были проблемы: Doxygen и, судя по всему, инструмент, поставляемый с Xcode: HeaderDoc. Имейте в виду, что это было несколько лет назад, поэтому ситуация, вероятно, немного изменилась.
Doxygen используется множеством проектов, но мне никогда не нравился стиль, который он генерирует. Не говоря уже о том, что это не было похоже на документацию на яблоки, и из того, что я мог сказать, заставить ее генерировать то, что я действительно хотел, было просто непрактично.
Первоначально HeaderDoc выглядел многообещающим. Фактически, некоторые файлы заголовков фреймворков включают HeaderDoc разметку, например:
/System/Library/Frameworks/CoreFoundation.framework/Headers/CFArray.h
Быстро стало очевидно, что HeaderDoc просто не собирается его сокращать. Это было медленно, очень медленно, и его вывод HTML был по существу "установлен в камне" - например, не было системы шаблонов. Что бы вы ни выбрали, задним концом является то, за чем вы застряли, за исключением некоторых незначительных изменений, которые вы можете сделать с таблицами стилей CSS.
Итак, что делать? Поскольку я уже отметил некоторые заголовки, используя 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 пришел позже, и, как вы можете догадаться из "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, потому что, когда он писал писать свои книги, требующие очень качественного набора математических формул, он был недоволен существующими решениями. Поэтому он провел несколько лет и написал свой собственный. Он был на краю современного компьютерного набора и типографии, а также из-за его созданных фрагментов в процессе.
Отметьте appledoc gentlebytes
Это выглядит великолепно! И его openource также!
Я уверен, что они используют нечто, называемое XEP компанией RenderX. Если вы посмотрите на PDF для языка программирования Objective-C, XEP указан как генератор PDF.
Если я прав, Apple создаст всю свою документацию в XML файле (кажется правдоподобным!). Затем вы запускаете этот файл через XEP и выводите его с правильным форматированием, ссылками и т.д.
Не прямой ответ на ваш вопрос, так как я уверен, что это не то, что использует Apple, но AppleDoc может стоить глядя в.
В его словах разработчика: "Идея такой утилиты исходила из-за отсутствия хорошего генератора документов для Objective C, который создавал красивую документацию". Из примера документации, представленной на сайте, ясно, что он хочет подражать макету Apple. У меня еще не было шанса попробовать себя, хотя.
Я не знаю о том, что использует Apple, но за последние несколько недель было два ответных вопроса о создании документации как для конечного пользователя, так и для разработчика.
Некоторые из них, безусловно, близки к тому, что Apple производит с точки зрения аккуратности и хорошей внешности, однако вам может понадобиться квалифицированный дизайнер, чтобы добавить этот определенный zazz. Не забывайте, что продукты Apple являются продуктом кропотливой, высококачественной детальной проектной работы, и просто использование инструментов, которые они использовали, не гарантирует автоматически одинаковые результаты.
Я думаю, что они создали много технической документации с Adobe Framemaker.
Даже для некоторых из новых продуктов (iPhone,...).
Это замечательно, потому что нет порта Mac OS X от Framemaker.
Интересно, что они используют в наши дни. Последняя версия Mac OS, способная запускать программное обеспечение System 9, - это Mac OS 10.4.11 в классическом режиме.
Возможно, вы хотите использовать какую-то автоматическую документацию по коду. Посмотрите Яблоки Headerdoc. Моя компания в настоящее время работает над рамками, и мы используем Doxygen (doxygen.org). Используя такие инструменты, у вас есть большая свобода создания нескольких форматов, таких как HTML или PDF, из одного источника, плюс у вас есть документация кода, неявно сделанная во время разработки.
