Что такое способ Mathworks для генерации документации HTML Matlab?

Question

Я работаю над общим кодом Matlab, и мы хотели бы предоставить сгенерированную документацию в виде HTML-документов с возможностью поиска в нашей локальной сети.

Я знаю из следующих методов для создания документации:

1. Написать конвертер для C++ - как файлы. Это делается в Using Doxygen with Matlab (Последнее обновление 2011 года) и mtoc++ (последнее обновление 2013 года). Затем файлы, похожие на C++, обрабатываются Doxygen.
2. Используйте Python's sphinxcontrib-matlabdomain для создания документации HTML.
3. Используйте m2html, который также является сторонним решением.
4. Другие варианты указаны в этом Q & As: One, Two и Three.

Все возможности не поддерживаются Mathworks. Все возможности требуют, чтобы я упоминал, например, параметры функции. Они не анализируют код в том смысле, Doxygen делает это за то есть Java:

//! an object representation of the advertisement package sent by the beacon 
private AdvertisementPackage advertisementPackage; 

Я слышал о publish() функции Matlab, но я ни разу не увидеть его использовать в вышеупомянутом смысле.

Вопрос: Что такое способ Mathworks для создания документации HTML Matlab. Можно ли проанализировать сам код? Могу ли я использовать информацию, предоставленную в Matlab Input Parser уже? Пожалуйста, укажите свои личные предпочтения в комментариях.

Пример:

%% Input parser 
p = inputParser; 
addRequired(p, 'x', @isnumeric); 

validationFcn = @(x) (isnumeric(x) && isscalar(x)); 
addRequired(p, 'fftSize', validationFcn); 
addRequired(p, 'fftShift', validationFcn); 

validationFcn = @(x) (isa(x, 'function_handle')); 
addRequired(p, 'analysisWindowHandle', validationFcn); 

parse(p, x, fftSize, fftShift, analysisWindowHandle); 

Answer 1

Я думаю, что вы хорошо изучили эту тему (как создать HTML-документацию из функций MATLAB), теперь вам решать, какой метод лучше всего подходит для вас.

Функция publish может использоваться для author documentation. Вы пишете обычные M-файлы с specially crafted comments (на самом деле файл может содержать все комментарии без кода), затем вы публикуете файл для получения визуализированного HTML (он также поддерживает other targets, такой как PDF, DOC, LaTeX и т. Д.). Подумайте об этом как о более простой версии Markdown, специфичной для MATLAB, которая используется здесь на Stack Exchange sites для форматирования сообщений.

Один из аспектов, о которых вы не упоминали, - это интегрирование сгенерированной документации в встроенный просмотр справки. Это делается путем создания файлов info.xml и demos.xml и организации документации определенным образом. Вы также можете сделать свои пользовательские документы доступными для поиска, построив индексные файлы Lucene с помощью функции builddocsearchdb (которая внутренне поддерживает функции поиска в пользовательских документах MATLAB). Обратите внимание, что неважно, как вы создали HTML-документы (вы могли бы использовать publish или даже вручную написанные HTML-файлы).

Фактически рабочий процесс, основанный на publish, можно расширить, и вы можете использовать его интересными способами, создав пользовательские файлы шаблонов XSL, чтобы преобразовать и обработать разобранные комментарии. Например, я видел, что он использовался для render equations, используя MathJax вместо того, чтобы полагаться на встроенное решение. Другим примером является publishing to MediaWiki markup (формат используется Wikipedia). Другие люди используют его для написания сообщений в блогах (см. official blogs на MATLAB Central, которые создают этот способ), или даже generate text files, обработанный статическими генераторами сайтов (например, и Octopress).

Насколько я знаю, нет доступных общедоступных инструментов, которые проверяют код MATLAB на более глубоком уровне и анализируют параметры функции. Лучше всего я мог бы придумать reflection, чтобы получить некоторые метаданные о функциях и классах, хотя это решение не идеально ...

MathWorks, похоже, использует собственную внутреннюю систему для написания HTML-документации. Жаль, что они не разделяют его с нами. :)

Answer 2

Я думаю, что это официально santioned способ MathWorks' написания документации: http://www.mathworks.co.uk/help/matlab/matlab_prog/display-custom-documentation.html

В основном написать HTML, и добавьте кучу файлов, чтобы сделать его доступным для поиска и отображаемым в документации MATLAB.

Answer 3

есть простой способ использовать публикацию с функцией & Соответствующие входы. посмотрите на publish('test',struct('codeToEvaluate','test(inputs);','showCode',false, )).