comando - ¿Cuál es la forma de Mathworks de generar la documentación HTML de Matlab?

plot matlab

Question

Estoy trabajando en el código compartido de Matlab y nos gustaría compartir una documentación generada como documentos HTML con capacidad de búsqueda dentro de nuestra red local.

Conozco los siguientes métodos para generar una documentación:

1. Escribe un convertidor en C ++, como archivos. Esto se hace en Uso de Doxygen con Matlab (Última actualización 2011) y mtoc ++ (Última actualización 2013). Los archivos similares a C ++ son luego analizados por Doxygen.
2. Utilice sphinxcontrib-matlabdomain de Python para generar una documentación HTML.
3. Use m2html, que también es una solución de terceros.
4. En esta sección, se enumeran más opciones: uno , dos y tres .

Mathworks no admite todas las posibilidades. Todas las posibilidades necesitan que mencione, es decir, los parámetros de una función yo mismo. No analizan el código en el sentido, Doxygen lo hace para, por ejemplo, Java:

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

Me enteré de la función publish () de Matlab, pero nunca vi que se usara en el sentido antes mencionado.

Pregunta: ¿Cuál es la forma de Mathworks de generar la documentación HTML de Matlab? ¿Se puede analizar el código en sí? ¿Puedo utilizar la información provista al Analizador de entrada de Matlab? Por favor, mencione su preferencia personal en los comentarios.

Ejemplo:

%% 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

Creo que esta es la manera oficial de escribir la documentación de Mathworks: http://www.mathworks.co.uk/help/matlab/matlab_prog/display-custom-documentation.html

Básicamente, escriba el código HTML y agregue un grupo de archivos para que se pueda buscar y mostrar en la documentación de MATLAB.

Answer 2

hay una manera fácil de usar publicar con una función y sus entradas correspondientes. mira publish(''test'',struct(''codeToEvaluate'',''test(inputs);'',''showCode'',false, )) .

Answer 3

Creo que ha investigado bien este tema (cómo generar documentación HTML a partir de las funciones de MATLAB), ahora depende de usted elegir qué método funciona mejor para usted.

La función de publish se puede usar para crear documentación . Usted escribe archivos M regulares con comentarios especialmente diseñados (de hecho, el archivo podría ser todos los comentarios sin código), luego publica el archivo para obtener HTML procesado (también admite otros objetivos como PDF, DOC, LaTeX, etc. .). Piense en ello como una versión más simple específica de MATLAB de Markdown que se usa aquí en los sitios de Stack Exchange para formatear las publicaciones.

Un aspecto que no mencionó es la integración de la documentación generada en el visor de Ayuda integrado. Esto se hace creando archivos info.xml y demos.xml , y organizando la documentación de una manera específica. También puede hacer que sus documentos personalizados puedan buscarse mediante la creación de archivos de índice Lucene mediante la función builddocsearchdb (que potencia internamente la funcionalidad de búsqueda en los documentos personalizados de MATLAB). Tenga en cuenta que no importa cómo generó los documentos HTML (podría haber usado publish o incluso escribir archivos HTML manualmente).

De hecho, el flujo de trabajo basado en la publish es extensible, y puede usarlo de maneras interesantes al crear archivos personalizados de plantillas XSL para transformar y representar los comentarios analizados. Por ejemplo, he visto que se usa para representar ecuaciones usando MathJax en lugar de confiar en la solución incorporada. Otro ejemplo es publicar en el marcado de MediaWiki (formato utilizado por Wikipedia ). Otras personas lo usan para escribir entradas de blog (ver los blogs oficiales en MATLAB Central que están creando de esta manera), o incluso generar archivos de texto procesados ​​posteriormente por generadores de sitios estáticos (como los frameworks Jekyll y Octopress ).

Hasta donde yo sé, no hay herramientas públicas disponibles que inspeccionen el código de MATLAB en un nivel más profundo y analicen los parámetros de la función. Lo mejor que se me ocurre es usar la reflexión para obtener algunos metadatos sobre funciones y clases, aunque esa solución no es perfecta ...

MathWorks parece estar utilizando su propio sistema interno para crear documentación HTML. Lástima que no lo compartan con nosotros usuarios :)