Linux ядро на сегодняшний день — самый динамичный, сложный, крупный проект с открытым кодом. Как же обстоят дела с его документацией? Существует прямая связь: чем качественнее и доступнее документация проекта, тем проще для посторонних изучить основы дела, освоиться и стать полноправным участником.

На семинаре Kernel Recipies мейнтейнер документации Linux ядра Jonathan Corbet рассказал о нынешнем положении дел с документацией и о том, как будет совершаться переход от анархии к порядку. Первые успехи в этом начинании уже есть. Некоторые документы были недавно конвертированы в ReStructuredText с помощью питоновского Сфинкса. О том как это было рассказано внутри.

Что содержит папка Documentation?

Documentation — единственная директория Linux, которая начинается с заглавной, это подчеркивает ее особую роль и положение, однако внутри черт ногу сломит.

• 2264 файла
• 228 директорий
• 23 MB документации, не считая Documentation/devicetree

Documentation/* is a gigantic mess, currently organized based on where random passers-by put things down last.
— Rob Landley, July, 2007.

Все это существует в двух ипостасях: обычные txt файлы и шаблоны DocBook, о которых есть что рассказать. Простые txt файлы никак между собой не связаны, написаны в разное время разными людьми и не все из них одинаково полезны. Некоторые из них известны всем разработчикам ядра. Таковыми являются ManagementStyle, написанный Линусом или CodingStyle, с которого начинают все волонтеры. Мне кажется эти документы должно прочитать всем разработчикам, линуксоидам и сочувствующим.

Btw, when talking about "kernel manager", it's all about the technical lead persons, not the people who do traditional management inside companies. If you sign purchase orders or you have any clue about the budget of your group, you're almost certainly not a kernel manager. These suggestions may or may not apply to you.

Если вы подписываете расходные ордера и разбираетесь в бюджетировании, тогда вы точно не старший разработчик ядра.

Утратившие актуальность доки внешне ничем не отличаются от остальных. Например, Documentation/applying-patches.txt инструктирует как скачать патчи через ftp и применить с помощью команды patch. Понятно, что сегодня никто так не делает.

# moving from 2.6.11 to 2.6.12
$ cd ~/linux-2.6.11                     # change to kernel source dir
$ patch -p1 < ../patch-2.6.12           # apply the 2.6.12 patch
$ cd ..
$ mv linux-2.6.11 linux-2.6.12          # rename source dir

# moving from 2.6.11.1 to 2.6.12
$ cd ~/linux-2.6.11.1                   # change to kernel source dir
$ patch -p1 -R < ../patch-2.6.11.1      # revert the 2.6.11.1 patch
                                        # source dir is now 2.6.11
$ patch -p1 < ../patch-2.6.12           # apply new 2.6.12 patch
$ cd ..
$ mv linux-2.6.11.1 linux-2.6.12        # rename source dir

Раскопки иногда дают удивительные результаты. Оказывается, Linux с 1996 г. поддерживает клингонскую письменность. Смотрим в Documentation/unicode.txt.

U+F8D0  KLINGON LETTER A
U+F8D1  KLINGON LETTER B
U+F8D2  KLINGON LETTER CH
U+F8D3  KLINGON LETTER D
U+F8D4  KLINGON LETTER E
U+F8D5  KLINGON LETTER GH
U+F8D6  KLINGON LETTER H
U+F8D7  KLINGON LETTER I
U+F8D8  KLINGON LETTER J
U+F8D9  KLINGON LETTER L
U+F8DA  KLINGON LETTER M
U+F8DB  KLINGON LETTER N
U+F8DC  KLINGON LETTER NG
U+F8DD  KLINGON LETTER O
U+F8DE  KLINGON LETTER P
U+F8DF  KLINGON LETTER Q

Документ Documentation/zorro.txt таит в себе секреты программирования драйверов для ПК семейства Amiga. Не удивительно, что последний раз доку правили в 2003-м.

Некоторые тексты настолько зубодробительные, что мало кто поймет. К таковым Джонатан отнес Documentation/memory-barriers.txt. Те, кто понял о чем идет там речь, по его словам, соображают лучше него и многих других.

В каталогах нижнего уровня тоже много старья, этот документ наверное из самых дремучих. Забавно, сто лет назад у меня тоже была электронная почта на usa.net, но после обвала на рынке DotCom, она стала платной и я пересел на Yahoo.

(5:521)$ less Documentation/sound/oss/MultiSound
#! /bin/sh
#
#  Turtle Beach MultiSound Driver Notes
#  -- Andrew Veliath <andrewtv@usa.net>
#
#  Last update:                      September 10, 1998
#  Corresponding msnd driver:        0.8.3

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

Теперь от чистой анархии plaintext файлов перейдем ко второй, гораздо более запутанной ипостаси документации ядра.

DocBook и ребята

Эти 34 шаблона XML со всей инфраструктурой обработки и есть DocBook. В отличие от простого текста, DocBook форматирование позволяет структурировать описание API, функций и получить на выходе html, pdf или man страницы, связанные между собой перекрестными ссылками.

(5:522)$ ll Documentation/DocBook/*.tmpl |wc -l
34

Исходный код содержит специальные вставки — kerneldoc comments. Таких вставок в коде свыше 55 тыс.

    /**
     * list_add - add a new entry
     * @new: new entry to be added
     * @head: list head to add it after
     *
     * Insert a new entry after the specified head.
     * This is good for implementing stacks.
     */

DocBook шаблон содержит инструкции о том, как из исходников выгружать документацию.

/*
 * Parse file, calling action specific functions for:
 * 1) Lines containing !E
 * 2) Lines containing !I
 * 3) Lines containing !D
 * 4) Lines containing !F
 * 5) Lines containing !P
 * 6) Lines containing !C
 * 7) Default lines - lines not matching the above
 */

Иллюстрация из файла Documentation/DocBook/networking.tmpl.

     <sect1><title>Socket Buffer Functions</title>
!Iinclude/linux/skbuff.h
!Iinclude/net/sock.h
!Enet/socket.c
!Enet/core/skbuff.c
!Enet/core/sock.c
!Enet/core/datagram.c
!Enet/core/stream.c
     </sect1>

После того как пользователь набирает команду make htmldocs программа scripts/docproc парсит в шаблонах инструкции экспорта документации и для каждой инструкции выполняет следующие действия.

• Находит в указанных файлах инструкции EXPORT_SYMBOL(), парсит их и добавляет названия функций в список экспортируемых символов.
• Вызывает Perl скрипт scripts/kernel-doc, который пробегает по функциям, структурам и всему прочему, что находит в Си коде для того, чтобы выцепить оттуда нужные определения.
• Вызывает по второму кругу scripts/kernel-doc и тот еще раз читает те же самые файлы, но на этот раз создает документацию тех самых функций и упаковывает результат в сниппеты DocBook.

Затем docproc распихивает в шаблоны созданные файлы с DocBook форматированием. Для HTML вызывается скрипт scripts/kernel-doc-xml-ref, который создает перекрестные ссылки, но только для отдельного шаблона. Наконец, xmlto производит на свет документацию в заданном формате, но можно указать и альтернативную программу в Makefile.

Эта мешанина скриптов, нескучных XML шаблонов, адских регулярок^[1] была ненадежной и тормознутой^[2], а главное — не производила радующей глаз, связной документации.

Markdown, Asciidoc, Sphinx

Понятно, что такое положение дел никого не устраивало и Джонатан вместе с коллегами искали выход из ситуации. Рассмотрев и перепробовав несколько вариантов, в конце остановились на связке ReStructuredTtext и Sphinx.

Вначале были сформулированы принципы. Новая система документации должна удовлетворять требованиям.

• Ликвидировать беспорядок.
• Улучшить форматирование и читабельность.
• Plaintext.
• Рационально организованный инструментарий.

Использование легковесных языков разметки напрашивалось само собой, и первой попыткой стал Markdown. Это позволяло решить сразу несколько проблем. Во-первых, комментарии написанные в самой программе, будут обновляться вместе с ней. Задумка в целом верная, хоть и оптимистичная. Во-вторых, документация, которую проще состряпать, имеет лучшие шансы быть написанной, так как текстовый MarkDown имеет гораздо более низкий порог вхождения чем DocBook-XML.

Вскоре, однако стало понятно, что MarkDown не может быть использован сам по себе а лишь в качестве надстройки актуального набора программ. Пришлось к коллекции регулярок kernel-doc добавить еще и поддержку MarkDown, что потребовало привлечь дополнительную утилиту конвертации pandoc (а затем asciidoc). Средства были явно не в ладу друг с другом, разметка плыла, отладка усложнялась. Тормозов стало больше, а инструментарий стал еще более капризным.

Тогда Джонатан сообразил, что выход из ситуации надо искать, двигаясь в обратном направлении. Вместо того, чтобы усложнять цепочку форматирования и взаимных преобразований, следует взять и выкинуть оттуда что-то лишнее. Этим лишним оказался DocBook и все, что вокруг него. Что, если все перенести в AsciiDoc и из него напрямую создавать необходимые html, pdf и man страницы, минуя инфраструктуру DocBook?

Легко сказать, трудно реализовать. AsciiDoc тянул за собой зависимости Ruby, плохо контачил с xmlto и все равно, скорее дополнял DocBook, нежели заменял его, а линковка документов все еще не срасталась. Тем не менее, было решено двигаться вперед вместо того, чтобы ждать непонятно чего. В последний момент Джонатан взял небольшой тайм-аут, еще раз взвесил все за и против и предложил взять на вооружение питоновскую систему документации Sphinx, основанную на легковесной разметке RestructuredText.

Почему Sphinx?

• Создан для документирования ПО. Например знает, что такое функция.
• Хорошо подходит для больших документов рассыпанных по множеству файлов.
• Часто используется и имеет хорошую поддержку^[3].
• Документы наконец-то связаны между собой.
• Тулчейн упростился, быстрее сборка.

Для того, чтобы убедить коллег Джонатан на коленке написал кривоватый Proof of Concept, а затем Jani Nikula отполировал его и довел до ума. Довольно быстро среди документалистов возник консенсус по данному вопросу и все завертелось. Кстати, трюк с PoC, всегда срабатывает по словам Andrew Morton-а, мейнтейнера mm ветки ядра. Так появился Linux, и так довольно часто решаются спорные моменты, когда надо заменить ужасное решение не идеальным.

Что удалось сделать и что еще предстоит

Изменения уже частично видны, в Documentation/Makefile.sphinx и Documentation/conf.py хранятся настройки Sphinx. Там же индекс файл index.rst и kernel-documentation.rst. Разработчики gpu и media впереди планеты всей и уже перевели всю документацию Documentation/gpu/ в Sphinx.

Процесс перехода на Sphinx будет происходить без шоковой терапии, т. е. plaintext файлы и DocBook шаблоны будут постепенно конвертироваться в новый формат по согласованию с остальными мейнтейнерами. Так что пока DocBook, никуда не денется, однако для новых rst документов docproc более не нужен.

Версия 4.8 — первое стабильное Linux ядро с новой системой документации. Линус прокомментировал эти изменения в письме, где с удивлением сообщил, что 20 процентов патча — документация.

The merge window has been fairly normal, although the patch itself looks somewhat unusual: over 20% of the patch is documentation updates, due to conversion of drm and media documentation from docbook to Sphinx doc format.
Linux Torvalds (4.8-rc1 release)

Хороший пример — документ HSI. До сих пор он существовал в двух ипостасях: plaintext и DocBook. Документы никак друг с другом не были связаны.

• Documentation/hsi.txt
• Documentation/DocBook/device-drivers.tmpl

Начиная с Linux 4.9 это будет единый документ Documentation/drivers-api/hsi.rst. И это только начало большого пути!

Впереди немало работы. Долгосрочная цель — полностью избавиться от DocBook и двадцатилетней Perl магии kernel-doc. Следует конвертировать более двух тысяч текстовых файлов в ReStructuredText, задать строгую и понятную иерархию файловой системы в Documentation, чтобы там был такой же порядок как в пространстве исходников ядра.

Если вы желаете принять участие в очистке авгиевых конюшен реформе документации Linux ядра, дерзайте, особых знаний для этого не требуется, хотя знания предметной области, конечно же, не лишние. Не менее важно учиться новым вещам, взаимодействовать со всеми заинтересованными сторонами и придерживаться здорового консерватизма и принципа постепенности.

Использованные материалы

• The present and future of formatted kernel documentation
• Kernel documentation with Sphinx, part 1: how we got here
• Kernel documentation with Sphinx, part 2: how it works

1. ^ Докладчик назвал kernel-doc bunch of regular expressions from the hell.
   
2. ^ У меня make htmldocs завершился через 8 мин. Для сравнения cpuinfo показывает bogomips: 4988.37.
   
3. ^ И что особенно приятно, не мы его поддерживаем