04.06 Документирование

Пример репозитория с документацией

• reStructuredText (не Markdown!)

• Sphinx

  • Установка и настройка

    • документация должна быть в каталоге doc

    • FIXME: четко расписать структуру дерева каталогов. Сказать, что картинки и пр. надо подкладывать НЕ в builds. Также были проблемы с открытием в браузере файла index.html: нет браузера в PATH (WSL), домашний каталог не виден из браузера (браузер под виндой, каталог под WSL). Чётко прописать, где искать index.html сгенерированной документации (builds/html/index.html).

    • FIXME: поскольку не было ДЗ к лекции, к-рое ко времени прака люди должны были сделать, люди НИЧЕГО НЕ ТРОГАЛИ и не споткнулись о косяки

  • Пример из двух файлов и картинки

  • Написать простой python-сценарий restcalend.py год месяц для преобразования календаря на месяц calendar.month() в таблицу reST. Должно получиться что-то такое:

    • .. table:: April 2024
      
          == == == == == == ==
          Mo Tu We Th Fr Sa Su
          == == == == == == ==
           1  2  3  4  5  6  7
           8  9 10 11 12 13 14
          15 16 17 18 19 20 21
          22 23 24 25 26 27 28
          29 30
          == == == == == == ==

    • Не забыть про пустую строку после ..table:: и сдвиг всей остальной таблицы

    • Достаточно поддерживать только такие месяцы, у которых 1-е число приходится на понедельник

  • Сгенерировать соответствующий файл и положить ссылку на этот файл в основной документ

  • Включить текст этого сценария в основной документ (параметры не нужны)

• sphinx.ext.autodoc

  • Настройка, в т.ч. добавление в conf.py команды подтягивания текущего каталога в пути для поиска исходников

  • Формирование индекса

  • Документирование функций

  • Переоформить написанный сценарий в виде модуля restcalend:

    • Классическая структура restcalend/__init__.py / restcalend/__main__.py (для вызова -m)

    • Предусмотреть указание года и месяца в командной строке

    • Убрать формирование reST-календаря в функцию restmonth() с параметрами как у calendar.month()

    • Задокументировать функцию и весь модуль

    • Задокументировать использование python3 -m restcalend год месяц в титульном листе

    • Включить ссылку на техническую документацию в титульный лист

• Тренировка в скриптовании перед Д/З. Напишите программу, которая:

  • реализует командный язык с двумя командами:

    • bless <строка> : напечатать "Be blessed, <строка>!"

    • sendto <строка> : напечатать "Go to <строка>!"

    • в обоих случаях <строка> не содержит пробельных символов (табуляций, пробелов и др.); проверять это в коде не нужно

  • получает команды из двух источников:

    • при запуске без параметров - из консольного ввода с использованием cmd

    • при запуске с параметром - из файла, имя которого передается через параметр
  • Для этого:

    1. Определить метод do_EOF(), возвращающий True

    2. Передать stdin=открытый_файл при создании интерпретатора

    3. Перед стартом .cmdloop() задать пустой .prompt и .use_rawinput = False

Д/З

Задача_1. Бродячие монстры и Сфинкс

• Скопировать решение Задачи_2 (где выделяются два модуля) с предыдущего занятия. Сделать коммит. Работать на ветке work.

• Добавить sphinx в pipenv

• Добавить на сервере MUD поддержку бродячих монстров:
  • один раз в 30 секунд (первый раз - по истечении 30 секунд от старта) выбирается случайный монстр, и он перемещается на одну клетку в случайно выбранном направлении (вправо/влево/вверх/вниз; помним, что поле "закольцовано")
  • если в результате перемещения монстр попал бы на клетку, где уже есть монстр, то перемещение НЕ ПРОИСХОДИТ, и проводится повторный выбор монстра и направления; и так пока не будет выполнено успешное перемещение монстра

  • при перемещении сервер выдаёт всем игрокам сообщение "<имя_монстра> moved one cell <направление>", где <направление> это right, left, up, down. Например: "manticore moved one cell right"

  • если монстр попадает на клетку, где есть игрок (или игроки), происходит "энкаунтер" - как если бы игрок(и) сам зашел(ли) на клетку с монстром
    • в т.ч. монстр отрисовывается у столкнувшихся с ним игроков, с произнесением приветственной фразы
• Для модуля-сервера задокументировать все функции, классы и модуль в формате autodoc
• Добиться выгонки технической документации по этим классам/функциям/модулю

  • Следить за тем, чтобы генераты (html-документация) не хранились в git (.gitignore), а настойки shpinx — хранились

• Оформить титульный лист документации (как минимум, скопипастить туда формулировку задачи)
• Сделать в титульном листе ссылку на техническую документацию

Задача_2. MUD-скриптование.

• Скопировать решение Задачи_1. Сделать коммит. Работать на ветке work.

• реализовать (см. последнее упражнение) получение команд из командного файла, если при запуске передан параметр "--file <имя_файла>"

  • командные файлы рекомендуется снабжать расширением ".mood"

• при получении команд из файла, ввод команд через cmd не должен работать

• чтобы не "зафлудить" сервер, интервал между последовательными отправками команд с клиента на сервер должен быть не менее 1 секунды
• примечание: скриптование нацелено на автоматическое тестирование MUD-ов, но при таком тестировании (когда дело до него дойдёт) "бродячих монстров" будет необходимо отключать