Разработка и анализ технической документации
2023/24 учебный год г., Институт математики и информационных технологий, II курс3 семестр
Направления бакалавриата:
- 09.03.04 - Программная инженерия
Материалы лекций
- Лекция 1. Введение в TeX.
- Лекция 2. Gnuplot, презентация, Beamer, Файлы презентации, презентация, документация.
- Лекция 3. Системы автоматической генерации документации. Doxygen.
- Лекция 3. Генератор статических сайтов.
- Лекция 4. Системы контроля версий документов. MediaWiki.
- Лекция 5. Техническая документация и технический писатель..
- Лекция 6. Обзор стандартов документации.. В.В. Липаев. Документирование сложных программных средств
- Корпоративные стандарты
Задания и сроки
Задание 1. Создание документа LaTeX
- Создать исходный файл документа LaTeX со своими именем, отчеством и фамилией латинскими буквами.
- Создать при помощи командной строки по исходному файлу документ в форматах DVI, PS и PDF (разными способами, см. latex, pdflatex, lualatex, latexmk, overleaf.com)
- Создать Makefile для автоматизации сборки (цели dvi, ps, pdf).
- Сформировать свой титульный лист(\vspace, \vfill, \hfill), задать структуру документа, разместить автоматическое содержание.
- Задать параметры страницы в документе следующим образом:
- Класс документа: report
- Размер страницы: A4;
- Поля(пакет geometry):
- Слева: 2 см;
- Справа: 1 см;
- Сверху, снизу: 2 см.
- Шрифт: 12 пт;
- Междустрочный интервал: полуторный.
- Сменить ориентацию одной из страниц документа на альбомную.
- Добавить в свойства документа свои И. О. Фамилию в поле "автор". Также заполнить поля "тема" и "ключевые слова".
- Добавить нумерованные и маркированные многоуровневые списки.
- Добавить несколько таблиц, использовать разные границы и объединение строк/столбцов.
- Продемонстрировать работу с цветом (фон страницы, фон блока, цвет текста и отдельных элементовм).
- Добавить в документ плавающее окружение figure с подключённым внешним рисунком.
- Подключить в документ пакет hyperref, настроить в нём отображение закладок, цвет гиперссылок.
- Вставить несколько фрагментов программного кода, использовать возможности пакета listings.
- Для ссылок на таблицы, рисунки, листинги и т. д. следует использовать соответствующие команды (\ref и т. д.).
- Добавить математический текст 1-2 страницы (формулы, теоремы и т.д., можно взять из Том 1, Том 2)
- Добавить библиографический список в конце документа
- Визуализация графиков, диаграмм и других математических объектов (gnuplot).
- Явные функции одной переменной, параметрическое представление кривых и кривые в полярных координатах.
- Поверхности, параметрическое представление поверхностей, сферические и цилиндрические координаты.
Задание 2. Создание презентации в beamer
Подготовить с помощью пакета beamer фрагмент научной презентации, состоящей из титульного листа и не менее восьми слайдов, которые должны, помимо прочего, содержать одну формулировку теоремы, одно определение, не менее двух нумерованных выключных формул. Между титульным листом и содержательными слайдами должен располагаться слайд с содержанием презентации. В начале каждой секции должен быть слайд оглавления с выделенным текущим разделом (или каждый слайд должен содержать в колонтитулах список разделов с выделением текущего). Презентация должна содержать интерактивные фрагменты (поэтапный показ элементов, смена элементов на слайде). Модифицируйте используемую тему (структура и цветовое оформление).
(Пример использования beamer: ex-beamer-utf.tex)
Документация пакета beamer на английском
языке Здесь. Некоторые
полезные примеры можно
найти Здесь .
Пример презентации:
возможности beamer .
Ну и еще пара полезных советов .
Задание 3. Автоматизация создания документации. Doxygen, JavaDoc.
На основе существующего программного проекта задать комментарии для автоматической генерации документацию. Дополнительные требования: задать форматирование титульного листа документации (README.md), деление элементов кода на модули (блоки), необходимо добавить перекресных ссылок на другие источники и разделы, используйте блоки специальных комментариев (todo, note и т.д.), используйте включение элементов кода в документацию.
Возможна сдача задания на основе другого языка программирования или другого инструмента генерации документации (python,javascript,php), многие среды разработке включают этот функционал или имеются плагины/пакеты для его подключения.
Срок: 26.11.2023Задание 4. Генератор статических сайтов.
- Используя любой генератор создать статический сайт.
- Необходимо уметь:
- Cоздавать простые страницы, составные страницы(блог/новостная лента/т.д.)
- Настраивать элементы дизайна и шаблоны
Задание 5. Работа с MediaWiki.
- Установка движка MediaWiki, конфигурирование(изменение логотипа, темы и тд.) и установка расширений (необязательный пункт).
- Используя установленную вами MediaWiki или общую на сервере кафедры создайте персональный раздел https://cs.petrsu.ru/wiki/ваш_login (используя механизм категорий)
- Создайте 1-2 шаблона для создания ваших страниц.
* Поробовать используя расширение Semantic Forms организовать ввод данных(создание/редактирование страниц) через формы(опционально для делавших п.0). - В рамках вашего персонального раздела создайте несколько (6-10) связных статей-страниц относящихся к разным подразделам (https://cs.petrsu.ru/wiki/login:page1 и т.д.)
- При форматировании ваших страниц используйте различные элементы (списки, таблицы, вставки изображений, вставка галлерей, цитирование, ссылки и др.) с разными параметрами.
Срок: 24.12.2023
Ссылки
- Львовский, С.М. Работа в системе LaTeX : курс / С.М. Львовский ; Национальный Открытый Университет "ИНТУИТ". - Москва : Интернет-Университет Информационных Технологий, 2007. - 465 с. ; [Электронный ресурс].[локальная копия]
- Беляков, Н.С. ТЕХ для всех. Оформление учебных и научных работ в системе LATEX / Н.С. Беляков, В.Е. Палош, П.А. Садовский. - Москва : Либроком, 2009. – 208 с. [Электронный ресурс].
- Документация MediaWiki.