Парсер JSDoc в виде расширения Sphinx для Odoo

Почему?

Потратил около недели в попытках заставить работать «стандартные» инструменты для javascript (jsdoc в надежде использовать расширение sphinx-js или documentation.js) и не смог получить ощутимый результат: не смог получить какой-либо результат с текущим состоянием документации, значительные изменения/дополнения/исправления в строках документации довели это до уровня «garbage output».

Отчеты об ошибках и сообщения в списках рассылки не ведут к улучшению кодовой базы на ES5 (если мы когда-нибудь синхронизируемся с модулями и классами ES6, все может быть по-другому, на самом деле большинство текущих усилий JSDoc, похоже, сосредоточены на функциях ES6/ES2015 ) но мой опыт, и просмотр списков рассылки подсказали мне, что много времени будет потрачено впустую.

Тем более, что я написал посетителей/рерайтеров для генерации документации из нашей существующей структуры, которая, в широком смысле, является относительно строгой, и поэтому

Что?

Если бы можно было генерировать аннотации JSDoc из наших четко определенных структур кода, было бы очевидно, что можно извлечь документальную информацию непосредственно из нее, следовательно, этот специфический для Odoo пакет/расширение пытается сделать именно это.

Этот пакет должен в конечном итоге обеспечить:

  • интерфейс командной строки, который может быть вызван через -m autojsdoc (при условии, что ваш PYTHONPATH может его найти), который должен позволять выводить проанализированный AST (абстрактно синтаксическое дерево)в удобной форме, возможно, делая поиск через AST, анализ графа зависимостей и текстовый дампер для документации.
  • расширение для sphinx (autojsdoc.sphinx), которое можно использовать для интеграции проанализированной информации JSDoc в документ Sphinx.

Как?

Помимо Sphinx, пакету требуется еще на 3 библиотеки:

  • pyjsparser, совместимый с Esprima синтаксический анализатор ES5.1 (с битами поддержки ES6), к сожалению, он не поддерживает комментарии в его текущей форме, поэтому мне пришлось его форкнуть. Опираясь на исходный код javascript, pyjsparser просто генерирует кучу вложенных словарей, представляющих Esprima ast, ast-types и достаточно неплохо описывает его, как только вы поймете, что «bases» - это просто структурные миксины.

    Поскольку оригинал этого не делает, этот пакет предоставляет модуль visitor для pyjsparser AST.

  • pyjsdoc это однофайловый «порт» jsdoc, на самом деле может выполнять большую часть синтаксического анализа JS (с использованием анализа строк), но его семантика ядра не соответствует нашим потребностям, поэтому я использую его только для анализа фактического содержимого JSDoc, и модуль jsdoc содержит некоторые измененные классы, расширения и манкей-патчи для вещей, которые сама pyjsdoc`_ не поддерживает на момент написания этой статьи:

    • баг в FunctionDoc.return_val
    • тип в FunctionDoc, поэтому он совместим с ParamDoc
    • более надежная функция анализа комментариев
    • заменен ModuleDoc т.к. оригинал не материализует модули AMD
    • расширение ClassDoc для поддержки миксинов
    • два дополнительных расширения CommentDoc для объектов «пространства имен» (набор атрибутов без дополнительной информации) и объектов mixin
  • pytest для настройки и запуска набора тестов, который вы можете запустить, вызвав pytest doc/ _extensions из верхнего уровня проекта, тесты представляют как «счастливый путь», который мы хотим проанализировать, так и различные шаблоны кода, которые сработали счастливый путь, потому что, например, они были сопоставлены и не должны иметь, они не были сопоставлены и должны были, или они были более сложными, чем ожидал счастливый путь