Информационное пространство дерева исходных текстов
Информация в исходном коде:
- Документирование самих исходных текстов: комментарии, встроенная документация
- Структура дерева каталогов и подразумеваемые файлы
- Собственно «документация»
Документирование исходных текстов
Задачи:
- Документирование исходного кода
- Создание технической документации «по месту»
Методы:
- Комментарии
- Конструкции ЯП
- Literate programming
На примере Doxygen:
Описания функций, макросов, классов…
Диаграммы (вызовы, классы, кооперации, каталоги, зависимости…)
- Навигация по коду (индексы, подсветка синтаксиса, поиск…) и перекрёстные ссылки
- Специфика самого проекта и вспомогательные тексты
- Внешние объекты (напр., иллюстрации)
- Несколько выходных форматов для разных целей (HTML, XML, man, LaTeX, PS/PDF…)
Использование размеченного текста (Markdown, HTML)
- ЯП: IDL, Java, C*, D, PHP, Python, Fortran, VHDL, VHDL
Python: самодокументируемость
Внешняя документация
- Man
*roff. Применимость man
Системы форматирования документации
Системы подготовки документации
- Подручные средства (Wiki, ODT, …)
Структура каталога с исходниками
Задачи:
Унифицировать начальные действия человека (AUTHORS, COPYING, INSTALL, NEWS, README, THANKS, TODO, …)
Разделять файлы по назначению (src, doc, lib, tests, po, …)
- Обеспечить раздельную сборку
- Структурировать области видимости
- Поддержка in-tree сборки
Пример автоматического создания проекта: http://kdevelop.org/KDevelop
Д/З
Реализовать пример использования Doxygen. Скачать документацию и посмотреть её
Снова GNU Hello так:
- Развернуть
- Добавить всё в git
Пересоздать файлы для Autotools с помощью autoreconf -fisv. Посмотреть, что изменилось
Запустить configure. Посмотреть, что изменилось. Собрать
- Изучить структуру каталогов.
- Собрать HTML-документацию. Скачать и посмотреть её.
Запустить pydoc.py и посмотреть навигатором на соответствующем порту
Как это сделать на сайте практикума? Написать свой собственный код на Python и посмотреть его pydoc-ом
pydoc sphinx