Есть отличная удаленная работа для php+codeception+jenkins+allure+docker спецов. 100% remote! Присоединиться к проекту

Быстрое создание документации для python проекта или создание reStructuredText файлов с SublimeText


(Mykhailo Poliarush) #1

Сейчас у меня есть задача создания документации к существующему фреймворку автоматизации, который написан на python. Для того чтобы документация была живая и поддерживаемая, она должна быть чем поближе к коду. Поближе к коду? Лежать вместе с кодом под одним версионым контролем, полностью или частично генерироваться с исходников и т.д.

Я выбрал http://sphinx-doc.org мега удобный инструмент, который позволяет мне сделать быструю и красивую документацию. Сам сфинкс описывать не буду, но вот хочу поделиться с вами инструментарием, который позволит быстро создавать нужный контент в нужном формате.

Сфинкс использует reStructuredText синтаксис для того чтобы создавать документацию. Потом с reStructuredText можно сделать и html и pdf, epub и т.д.

Для того чтобы создавать reStructuredText я использую мой любимый SublimeText. Редактор имеет сразу встроенные возможности создавать и подсвечивать нужные файлы, но этот процесс можно немного упростить за счет установки дополнительных плагинов.

  1. https://sublime.wbond.net/packages/RestructuredText%20Improved улучшает во многом подсветку нужных элементов
  2. https://github.com/mgaitan/sublime-rst-completion добавляет очень удобный автокомплит и навигацию по rst файлам.

После всех установок rst файлы будут выглядеть вот так вот:

По второму плагину даже есть видео:

Также sublime-rst-completion добавляет возможность делать preview html или другого формата выходных данных.

Ну и последнее, в моей небольшой заметке, если Вы описываете rst файлы, то нужно их компилировать в html. И этот процесс можно также автоматизировать через функции build в sublime. Т.е. компилировать выходные файлы не выходя из самого редактора.

Для этого нужно сделать несколько действий в sublime:

{
    "working_dir": "${folder}\\docs",
    "cmd": "make.bat clean & make.bat html"
}
  • и по Ctrl+B все ваши rst файлы будут компилироваться в нужный вам формат.

А дальше нужно только просмотреть, чтобы текст красиво смотрелся.

В результате получаем вот такую вот документацию с возможностью поиска, привязке к коду, автоматической подсветкой кода, генерации индекса классов и методов и т.д.:

А как Вы документируете Вашу автоматизацию? И какие процессы и \ или инструменты используете?


(Artur Korobeynyk) #2

Только хардкор, только недокументированный API )) Комменты в коде и то не ко всему.


(Mykhailo Poliarush) #3

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

Кстати еще забыл добавить в посте. Что документация, в виде артефактов для jenkins, видна через веб-интерфейс, потому никому никаких действия делать не надо, а только читать и размышлять :smile:


(Александр Таранков) #4

Полноценной документации по методам нет.

  1. Есть комментарии в коде к классам и методам
  2. Есть ссылки на задачи и баги, по результатам которых во фреймворк вносились изменения
  3. Есть how-to статьи для старта
  4. Есть статьи с описанием ключевых особенностей архитектуры

А дальше - копание в коде, репозитории и багтрекере :smile:

Фреймворк для внутреннего использования и пользуются им 3 человека, включая меня. Так что я сам - документация :smile:

Документация по методам конечно пригождается, но я не считаю, что этого достаточно. ИМХО, важнее, когда видишь как пишутся тесты, что при этом используется и т.д.


(Artur Korobeynyk) #5

Не, я то считаю что документация должна быть. Она здорово помогает, когда кто-то приходит в комманду… или использует чужой код. Просто такая традиция сложилась, люди в комманде не меняются очень долго, так что никому документация не надо. Любой новичек, который не повесится, через пол года тоже не будет в ней нуждаться.


(Sergey Korol) #6

Пишу javadocs только для тех классов, которые будут действительно важны для команды, к примеру, BasePage. В IntelliJ есть замечательная встроенная функция генерации джавадоков, так что нет необходимости в установке external tools. Ну и как заметили выше, дополнительно описываются различные how-to и архитектурные доки.