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

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

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

  • Запишите конвертер в файлы на С++. Это делается в Использование Doxygen с Matlab (Последнее обновление 2011) и mtoc++ (последнее обновление - 2013). Затем файлы, похожие на С++, обрабатываются Doxygen.
  • Используйте Python sphinxcontrib-matlabdomain для создания документации HTML.
  • Используйте m2html, который также является сторонним решением.
  • Дополнительные параметры перечислены в этом Q & As: Один, Два и Три.

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

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

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

Вопрос: Каков способ 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);

Ответы

Ответ 1

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

Функция publish может использоваться для авторской документации. Вы пишете обычные M файлы с помощью специально созданных комментариев (на самом деле файл может содержать все комментарии без кода), затем вы публикуете файл получить отображаемый HTML (он также поддерживает другие цели, такие как PDF, DOC, LaTeX и т.д.). Подумайте об этом как о более простой версии Markdown, специфичной для MATLAB, которая используется здесь, на сайтах Stack Exchange для форматирования сообщений.

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

Фактически рабочий процесс publish расширяем, и вы можете использовать его интересными способами, создав собственный XSL template файлы для преобразования и обработки обработанных комментариев. Например, я видел, что он использовал рендеринг уравнений, используя MathJax вместо того, чтобы полагаться на встроенное решение. Другим примером является публикация в разметке MediaWiki (формат, используемый Wikipedia). Другие люди используют его для написания сообщений в блогах (см. официальные блоги в Центре MATLAB, которые создают этот способ) или даже генерировать текстовые файлы, обработанные позже статическими генераторами сайтов (например, Jekyll и Octopress рамки.)

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

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

Ответ 2

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

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

Ответ 3

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