Создание документации на основе исходных кодов MQL5

Введение

Любой разработчик рано или поздно сталкивается с необходимостью создания документации к своей работе. Написание инструкций и всякого рода справок — неотъемлемая часть повседневной деятельности и общения с заказчиком. Кроме того, со временем накапливается множество библиотек и фрагментов кода, в том числе и чужого. Разобраться со всем этим материалом поможет аккуратно выполненная документация. Если при написании кода сразу иметь в виду необходимость разработки справочных материалов, то затраты времени на это сводятся к нулю. Необходимые комментарии и тэги проставляются одновременно с созданием кода. На первый взгляд, выполнение этой работы кажется необязательным, но если ее сделать, то впоследствии это сэкономит разработчику массу времени и нервов.

Рассмотрим процесс создания документации от начала до конца, останавливаясь на важных моментах. Ранее уже была написана статья на эту тему, однако не вся информация, изложенная в ней, актуальна по сей день, не все методы работоспособны. Постараемся развить и продолжить тему. В основном будем рассматривать работу с программой Doxygen, используя Doxywizard.exe:

Добавление файлов MQL в Doxygen

Итак, наша цель состоит в том, чтобы  получить справочный / презентационный файл по уже написанному коду, расположенному в одном или нескольких файлах с уже нанесенной разметкой. В результате работы будет получен файл  в формате chm. Помимо этого, создадим файлы формата html, которые и сами могут справиться с презентационными или справочными задачами. Как я уже сказал, будем пользоваться программой Doxygen, которая подходит под наши цели.

Описание процесса настройки программы и вывода итоговых файлов приведено в вышеупомянутой статье, но с момента ее публикации прошло очень много времени, и если сейчас сделать все так, как в ней описано, то ничего не получится. Программа отработает, не будет ни замечаний, ни сообщений об ошибках, но никаких файлов создано не будет.

Поэтому первое, что мы сделаем —  решим эту проблему, внеся коррективы в настройку программы. Запускаем doxywizard.exe и начинаем настраивать, указываем имя проекта, входную и выходную папку, Обязательно отмечаем "Optimize for C++ output" в пункте Mode вкладки Wizard.

Переходим на вкладку Expert и в пункте Input добавляем файлы с нужным расширением:

Теперь Doxygen будет знать, что ему надо парсить файлы с нашими расширениями, но этого недостаточно! Программе нужно явно указать, что файлы с расширением .mq* — это аналог файлов с расширением .с, выполнить "отображение" расширений (вероятно, так можно назвать данное действие):

Начиная с этого момента, Doxygen начинает парсить наши файлы и выдавать результат.

Кодировки

Поговорим об еще одном недостаточно освещенном источнике проблем — о проблемах, связанных с кодировкой исходных и итоговых документов.

Если язык документации будет английский, то никаких проблем не возникнет. Однако если мы хотим получить документацию на другом языке, то увидим нечитаемые символы. Причина в том, что по умолчанию все документы считаются созданными в кодировке UTF-8. Если фактически часть документов имеет другую кодировку, то текст станет нечитаемым. Рассмотрим решение:

1. Определимся с языком и кодировкой по умолчанию. Это будут UTF-8 и русский язык:
   

   
   

   
   

   
   

   
   

   Нужно заметить, что мне так и не удалось выполнить изменение DOXYFILE_ENCODING. Какая бы кодировка не была задана в этом поле ввода, реально подставляется все равно UTF-8. Вероятно, заменить кодировку в этом месте можно единственным способом — явно прописать её в файле, которым потом заменить "Head" по умолчанию (это было рассмотрено выше). Однако таким образом вряд ли можно будет достичь желаемого результата.
   

2. Указать кодировку, в которой созданы исходные документы, ведь это не обязательно будет UTF-8. В нашем случае скорее это будет кодировка CP1251. Если часть документов создана в одной кодировке, а часть — в другой, то перекодируем файлы так, чтобы для всех исходных документов была только одна кодировка, и прописать её в этом поле ввода:
   

   
   

   
   

   
   

3. И, наконец, если у нас предполагается вывод в формат справки CHM, то придется явно указать, какая кодировка используется в HtmlHelp индексе (файл с расширением hhk):
   

   
   

   
   

   
   

   Для желающих еще более подробно вникнуть в данный вопрос прикрепляю статью о том, как создавать испанскую и английскую документацию, используя Doxygen.

Теперь остановимся на более общих моментах, которые видятся наиболее важными, в частности — на внешнем виде генерируемого html-файла.

Заголовок и "подвал" страницы

Доступные опции расположены на вкладке Expert, в пункте HTML. Очевидно полезными оказываются переключатели, позволяющие подключать к созданию итоговой документации пользовательские html-файлы — поля HTML_HEADER, HTML_FOOTER и HTML_STYLESHEET. По названиям полей понятно, за что отвечает каждое из них — за заголовок на каждой странице, за "подвал" на каждой странице и за стили отображения. Напоминаю: чтобы html-файлы вообще генерировались, должен быть отмечен переключатель GENERATE_HTML на этой вкладке.

Оба рассматриваемых html-файла пишутся по особым правилам, хотя для файла footer.html у меня сработал просто кусок html-текста без всякого заголовка, без оформления, просто в таком виде:

<div>
  <h1 style="text-align: center;">Footer</h1>
</div>

Но лучше придерживаться правил. Чтобы понять, как именно могут быть устроены пользовательские файлы, мы можем сгенерировать те, которые используются программой по умолчанию. Мы получим не только два искомых html-файла, но и таблицу стилей. Сделаем это такой командой:

 - doxygen -w html new_header.html new_footer.html new_stylesheet.css

Вот фрагмент файла new_footer.html:

<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    $navpath
    <li class="footer">$generatedby
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
  </ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> $doxygenversion
</small></address>

Сразу бросаются в глаза многочисленные плейсхолдеры, перечень и назначение которых имеется в документации. Можно легко понять, где именно выводится реклама самого Doxygen, а где можно поставить свои ссылки. Аналогично можно будет исправить и new_header.html, а при желании — и таблицу стилей, и последовательно подключить их на указанной вкладке. Таким образом, можно существенно изменить внешний вид итоговой документации в своих целях.

Препроцессорная обработка

Doxygen позволяет предварительно обрабатывать файлы. Это делается, чтобы дать возможность программе обработать макросы типа BEGIN_MESSAGE_MAP и конструкции типа __declspec из Visual Studio. Для наших скриптов это не так актуально, поэтому мы здесь просто отметим такую возможность, не углубляясь в детали. Настраивается этот механизм в пункте Preprocessor вкладки Expert. Отметим также возможность создания внешних фильтров, цель которых — преобразовать входной файл так, чтобы его мог понять Doxygen. Такой фильтр представляет собой внешнюю консольную программу, в командную строку которой добавляется имя обрабатываемого файла. Сама же программа-фильтр представляет собой в основном набор регулярных выражений, преобразующих, например, программу на ассемблере, к виду, понятному Doxygen. Стоит применять препроцессорную обработку или нет, решать разработчику. Можно, например, с помощью этого механизма попытаться сделать понятной для Doxygen конструкцию #property.

Подключение примеров

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

/** \example filename.ext
 * This is an example of how to use ....
 */

Здесь определяется имя файла с примерами. Во второй строке можно перечислить, какие именно функции или классы проиллюстрированы примерами. Но этого недостаточно: мы пока не знаем места, где расположен файл. Путь к файлам с примерами следует указать явно в Doxygen. Делается это так, как показано на картинке:  указываем путь к файлам и паттерны их имен:

Добавляя несколько путей и используя флажок EXAMPLE_RECURSIVE, можно подключать к нашей документации множество файлов с примерами, получая в результате прилично развитую справку.

HTML-тэги

Еще одно полезное умение Doxygen — работа с фрагментами html-разметки, которую можно размещать прямо в блоках комментариев. В документации к программе имеется весьма солидный перечень тэгов html, которые сможет обработать Doxygen и вставить в итоговый документ. Например, вот такой текст вставит в описание макроса ссылку и таблицу с заголовком:

/*!
  \def def_example
  \brief <a href="http://www.google.com">links to google</a>
         <table>
           <caption>Single table</caption>
           <tr>
             <td>One</td>
             <td>two</td>
           </tr>
         </table>
*/
#define def_example "Some define"

Совместно с html-разметкой можно использовать псевдосимволы типа  

При использовании ссылок есть еще одна особенность — Automatic link generation. На практике это означает, что Doxygen будет преобразовывать в правильную ссылку и вставлять в итоговый документ текст типа https://www.mql5.com. Таким преобразованием Automatic link generation не ограничивается. Можно создавать ссылки на файлы, классы, отдельные функции. Это служит в интересах создания разделов документации типа "See Also". В целом, такая разметка позволит еще лучше описать нужный фрагмент кода, использоваться для разметки типа "Prev/Next" и более развитых форм пагинации, может послужить в интересах SЕО и рекламы.

Титульная страница

Выше было уже сказано о возможности заменять код в заголовке и в "подвале" страниц на свой. Помимо этого, у разработчика есть возможность разработать отдельный дизайн для титульной страницы. Для этого он должен указать в одном из файлов, что его содержимое является титульной страницей. Это выполняется с помощью тэга \mainpage, включаемого в начало файла:

/*! \mainpage My Personal Index Page
* \image html i.jpg
 */

В этой разметке объявляется, что файл, в котором она находится, является титульной страницей с заголовком "My Personal Index Page", после которого будет вставлено изображение "i.jpg". Изображение должно быть заранее подготовлено, а путь к нему — известен Doxygen:

Помимо изображений, можно вставлять файлы и других типов.

Вывод в форматах html и HtmlHelp

Создавать документацию можно в нескольких форматах. На вкладке Wizard в пункте Output можно отметить необходимые. Первым идет создание документации в обычном html. В папке, указанной в качестве выходной, будет создан файл index.html. Это и будет основной файл всей документации. Однако такой формат не всегда удобен. Поэтому рассмотрим создание документации в формате HtmlHelp. Для этого нужно отметить переключатель HTML и "prepare for compressed HTML" в том же месте и на той же вкладке. Кроме того, на вкладке Expert в пункте HTML в поле ввода CHM_FILE зададим имя файла HtmlHelp справки с расширением, а в поле ниже (HHC_LOCATION) — путь доступа к компилятору справки hhc.exe. Это необязательный параметр. Если поле останется пустым, то будут подготовлены все необходимые файлы, а справку в формате chm придется получать отдельным вызовом программы HTML Help Workshop.

Там же есть еще несколько переключателей для более тонкой настройки. Особое внимание стоит обратить на GENERATE_CHI. По умолчанию этот переключатель сброшен. Но если его установить, то Doxygen сгенерирует отдельный индексный файл с расширением CHI. Если впоследствии этот файл удалить, то пользование основным файлом справки будет крайне затруднено. Практически вся справка в формате HtmlHlp утратит львиную долю функциональности.

О том, как настраивать кодировки, уже было сказано. Остается перейти на вкладку Run и нажать кнопку "Run Doxygen". После целой страницы технических сообщений Doxygen сообщит об окончании работы. Внизу имеется кнопка "Show HTML output" для просмотра документации в браузере. Файл в формате HtmlHelp нужно будет найти и запустить вручную.

Небольшое видео по работе с Doxywizard:

Далее рассмотрим несколько второстепенных, но интересных моментов.

Возможности редактора Sublime Text 3 по расстановке тэгов в коде на MQL5

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

Заниматься расстановкой придется в редакторе MT5. При этом нужно будет внимательно отслеживать появляющиеся ошибки. Этот процесс можно немного упростить и частично автоматизировать. Воспользуемся редактором Sublime Text 3. Он распознает MQL4, а следовательно, может работать и с MQL5. Подключаем в редакторе оба пакета, имеющих отношение к MQL.

Затем устанавливаем пакет, который способен работать с нужной нам разметкой — DoxyDoxygen. В нем есть хоткеи, он способен выполнять перевод на разные языки и делать автодополнения. Этот пакет поможет быстрее и с меньшими затратами расставить правильно все нужные тэги. Как написано в документации (её можно будет найти в прикрепляемых файлах), после окончания разметки Doxygen можно будет вызвать прямо из редактора. Там же, в прикрепленной документации, можно найти описание процесса конфигурирования пакета.

В целом, никаких особых вопросов, тонкостей и проч. в работе с описанными пакетами нет, поэтому не будем на этом подробно останавливаться.

Вывод в форматах pdf и djvu

В Doxygen предусмотрена эта интересная возможность, но к сегодняшнему дню работа по ее реализации еще не завершена. Пытаться выводить документацию в этих форматах можно уже сейчас, некоторая информация об этом есть в документации к Doxygen, есть и отдельные статьи и инструкции на сторонних сайтах. Здесь рассмотрим вывод в формате pdf немного подробнее.

1. На вкладке Wizard в пункте Output нужно отметить вывод в формате LaTeX и выбрать формат "for PDF". В документации написано, что нужно отметить GENERATE_PERLMODE на вкладке Expert в пункте PerlMod, но мы пропустим этот шаг.
2. Выполним другие необходимые настройки, в том числе настроим вывод в форматах CHM и html (при необходимости).
3. Создадим необходимые документы.

В выходной папке будет создана папка latex, куда будут помещены файлы этого формата. На этом работа с Doxygen заканчивается. Теперь необходимо преобразовать файлы из формата latex в формат PDF. Я воспользовался программой MikTex, взятой здесь в форме portable. Устанавливаем и запускаем программу. Выбираем в ней TeXworks. В окне редактора ищем и открываем файл refman.tex, который нам создал Doxygen в папке latex. Далее на панели инструментов редактора из комбинированного списка выбираем XeLaTex и кликаем на большую зеленую кнопку левее. Наблюдаем ряд диагностических сообщений. В процессе работы редактор предложит установить дополнительные пакеты (нужно согласиться). Если вывод завершен с ошибкой, то "компиляцию" можно попытаться повторить.

В результате в той же папке latex будет создан  файл refman.pdf с нашей документацией. Качество вывода оставляет желать лучшего: очевидно, что нужно дополнительно редактировать оформление. Возможно, многих недочетов можно было избежать, редактируя исходные файлы latex. Однако не будем забывать, что работа по внедрению этой возможности еще не закончена, поэтому подождем официального подключения опции к Doxygen.

Практическое использование

Перейдем к конкретным примерам и покажем, как можно использовать Doxygen и другие программы для создания документации. Начнем с создания документации для стандартной библиотеки — набора классов в \MQL5\Include. Используем простой способ: прогоним по всем файлам программу DoxyGen, без расстановки дополнительных тэгов в самих файлах. Это не даст возможности получить дополнительную важную информацию об элементах библиотеки, но мы увидим, что именно мы сможем получить. Возможно, нас устроит полученный результат. Для начала допустим, что все нужные программные компоненты уже установлены на компьютере. Итак, начнем:

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

• Запускаем Doxygen и начинаем его настраивать. Для предварительной настройки можно использовать прилагаемый файл MQL5Doxygen.zip. Чтобы воспроизвести процесс на своих файлах, необходимо будет перенастроить Doxygen под себя. Задайте свои пути для файлов, свое имя проекта, обратите внимание на кодировку и язык.
  
• Особое внимание обратим на вкладку Wizard, пункт Output. В качестве формата для вывода используется plain html с отмеченным пунктом "With search function". Это означает, что файл в формате HtmlHelp сгенерирован не будет. Если выбрать "prepare fo compressed HTML (.chm)", то с пункта "With search function" отметка не будет снята, однако в конце мы получим замечание о невозможности использования этого пункта. Но наша цель — получить и то, и другое.
  
• Поэтому генерацию придется выполнять дважды. Первый раз, используя простые настройки из файла MQL5Doxygen.zip, получим документацию только в формате html в папке, предназначенной для вывода. Начало всей документации находится в файле index.html.
  
• Повторяем генерацию, изменив настройки. Снимаем отметку с пункта "With search function". Отмечаем  "prepare fo compressed HTML (.chm)". Переходим на вкладку Expert, пункт HTML. Обращаю внимание на то, что должно быть задано CHM_FILE  — имя файла С РАСШИРЕНИЕМ, в котором будет HtmlHlp справка, а также путь доступа к компилятору hhc.exe  в HHC_LOCATION. Если эти переменные не будут инициализированы, то Doxygen подготовит исходные файлы для HtmlHlp справки, но саму справку сделать не сможет, и HTML Help Workshop придется запускать отдельно. После внесения изменений в настройки можно начать генерацию. В результате получим документацию в формате html (как при первом прогоне, но без поиска) и справку в формате HtmlHlp. Результаты работы и файл настроек можно найти в прилагаемом архиве StandardLibrary.zip, из которого убраны малоинтересные файлы html формата. Желающие все-таки получить справочную документацию к стандартной библиотеке в формате html теперь могут легко сделать это самостоятельно.
  

Продолжим следующим примером. На этот раз постараемся разметить файлы с кодом тэгами и улучшить их внешний вид.

• Для начала создадим два файла с простейшим тестовым кодом. Попытаемся придать ему определенное "разнообразие". Создадим титульную страницу mainpage.mq5, которую сразу разметим нужными нам тэгами. Кроме того, разместим на титульной странице картинку. Все три файла (кроме файла с картинкой) поместим в папку, которую определим в качестве "Source code directory" на вкладке Wizard пункте Project. Здесь же определим папку для вывода и при желании — логотип проекта.
• Создадим папку для картинки и поместим её туда. Создадим файл footer.html путем редактирования файла, который Doxygen использует для "подвала". Цель — убрать рекламу самого Doxygen. Желающие могут добавить сюда что-то своё, но я обращаю внимание на предупреждающие надписи в самом файле: "is needed for treeview function!", что призывает к аккуратности. Вносим изменения в настройки, указывая, где лежит картинка и новый файл для "подвала". О том, как это сделать, мы уже говорили выше.
• Создадим один файл с тестовым примером использования данного кода. Расположим его в отдельной папке и укажем Doxygen, где его искать.
  
• Теперь, когда структура проекта создана, открываем файлы с тестовым кодом и размечаем их тэгами так, как считаем нужным. Используем Sublime Text 3 с установленным набором пакетов, о котором говорится в начале статьи. В прилагаемом архиве будет один из вариантов такой разметки, но, очевидно, далеко не единственно верный.
• Вносим заключительные изменения в настройки Doxygen. Следует учитывать возможную необходимость выполнить вывод в два этапа, как описано в прошлом примере.
  
• Выполняем вывод. Получаем документацию в формате HTML. Изменяем настройки. Получаем документацию в формате HtmlHelp.

Весь проект, исходные файлы, файл настроек Doxygen и итоговая документация в обоих форматах находится в прикрепленном архиве Custom_HTML_CHM.zip.

Заключение

В данной статье мне хотелось максимально уйти от цитирования документации к различным программам и сосредоточиться на сложных моментах, сулящих эффектный внешний вид документации. Для желающих максимально полно ознакомиться со всеми тэгами и переключателями Doxygen прикрепляю документацию к программе в формате CHM. Для пакетов  Sublime Text 3 имеется встроенная документация, а сам редактор очень хорошо известен.

Описание прикрепленных файлов.

Имя	Описание
Using_Doxygen_to_generate_Spanish_and_English_documentation.zip	Статья в формате pdf
Doxygen_Manual.zip	Документация в формате chm к программе Doxygen
DoxyDoxygen.zip	Документация в формате pdf к пакету DoxyDoxygen
MQL5Doxygen.zip	Файл настройки Doxygen
StandardLibrary.zip	Полученная документация в формате CHM
Custom_HTML_CHM.zip	Полученная документация в формате html и CHM