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

При работе с WSL могут возникнуть проблемы с открытием HTML в браузере, потому что HTML в Linux, а браузер — в Windows

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

• reStructuredText (не Markdown!)

• Sphinx

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

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

    • make -C doc html; где появится результирующий HTML

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

  • Написать простой 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
          == == == == == == ==

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

  • Если месяц начался не с понедельника, вставим нужное количество r"\ " в начало недели

    .. table:: July 2026
    
        == == == == == == ==
        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 31
        == == == == == == ==

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

• sphinx.ext.autodoc

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

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

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

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

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

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

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

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

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

• Финальный вариант:

  .
  ├── doc
  │   ├── API.rst
  │   ├── conf.py
  │   ├── index.rst
  │   ├── make.bat
  │   ├── Makefile
  │   └── month.rst
  └── restcalend
      ├── __init__.py
      └── __main__.py

• скриптование в cmd при помощи задания cmdqueue (в примере из лекции перекладываем туда sys.argv[1:], если оно есть)

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

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

    • 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-ов, но при таком тестировании (когда дело до него дойдёт) "бродячих монстров" будет необходимо отключать