如何在 Octave 中记录一个函数？
How to document a function in Octave?
MATLAB 中的 publish 函数适用于脚本和函数，
而 Octave 仅适用于脚本：如果我输入
publish myFunc.m
八度给出
error: publish: Only Octave script files can be published.
我可以在 Octave 中发布函数吗？如果是，如何？
这是一个 "multiple questions in one" 问题，中间有很多假设，所以让我们先解决这些问题：
1. 我将从评论中的问题开始，因为这是最简单的：Matlab 的发布者不是 代码文档工具。这是一个 "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" 工具。因此，您指向的 link 在这种情况下根本无关紧要，因为它讨论的是 matlab 代码的文档。
2. 事实上，matlab 的发布者也 "works for functions"，特别是这里的第一点，应该被认为是一个错误而不是一个功能，或者最多作为一个微不足道的未记录的扩展。如果您查看 publish 命令的 matlab documentation，您会发现它需要一个文件名，而不是带参数的函数，并且文档仅讨论脚本而没有提及 'function' 兼容性。
3. 此外，即使您 确实 想将发布者用作 "documentation tool"，这对于函数来说也是违反直觉的在这种格式中，由于您需要提供参数以使发布者工作（不会在实际报告中显示），因此您需要一个显示中间计算的修改版本（与可能不会显示的普通版本相反） ), 该函数只是在报告末尾喷出一个难看的 ans= blabla 。如果您的最终目标是文档，那么最好为此编写一个定制脚本，显示正确的用法和示例，就像 matlab 在其 actual 文档中所做的那样。
说了这么多，是的，'cheat'您可以在发布的报告中包含函数代码，也就是说，在 Octave 中（从 R2016b 开始也是 matlab），可以在本地定义函数。仅包含函数定义的 .m 文件被解释为函数文件，但如果在函数定义之前还有其他 non-function-declaration 指令（注释除外），则它被视为脚本。因此，如果您发布此脚本，您将有效地获得包含功能代码的已发布报告：
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
（如果您对必须手动创建 'wrapper script' 不满意，您可以随时创建自己的包装函数来自动执行此操作）。
但是，matlab 和 Octave 发布者都是受限工具设计。正如我之前所说，它更像是一个 "quick report to show numbers and plots to your supervisor" 工具，而不是一个 "make nice documentation or professional reports" 工具。相反，我会投资于一个很好的自动化乳胶工作流程，看看用于显示代码的代码格式化工具，然后简单地将代码包装在一个脚本中，该脚本将输出生成一个文件，然后您可以将该文件导入乳胶。这听起来可能需要更多工作，但从长远来看，它更加灵活和强大，特别是因为格式化命令可能非常古怪且有限。
您可以使用 Octave Forge generate_html 包，它可以生成 html 个单独的函数。它主要用于生成 Octave Forge 包的文档，其默认值反映了这一点，但您可以添加任何您想要的样式。
此包将使用 Octave 中的 help 函数看到的相同帮助文本，这是文件中不是以 Copyright 或 Author 开头的第一块注释.你可以使用纯文本，但为了更好的格式，你可以使用 Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text 包括一个关于 Texinfo 语法的简短部分（实际的 Texinfo 手册可能有点让人不知所措）。
除了帮助文本，generate_html 包还识别 %!demo blocks 并生成一个包含演示代码的部分和它生成的输出，包括数字。
查看帮助文本和演示块在 Octave 中如何工作的最佳方法是检查源代码（正如@Andy 在评论中指出的那样）。例如，请参阅 source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page（注意演示块）。
MATLAB 中的 publish 函数适用于脚本和函数，
而 Octave 仅适用于脚本：如果我输入
publish myFunc.m
八度给出
error: publish: Only Octave script files can be published.
我可以在 Octave 中发布函数吗？如果是，如何？
这是一个 "multiple questions in one" 问题，中间有很多假设，所以让我们先解决这些问题：
1. 我将从评论中的问题开始，因为这是最简单的：Matlab 的发布者不是 代码文档工具。这是一个 "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" 工具。因此，您指向的 link 在这种情况下根本无关紧要，因为它讨论的是 matlab 代码的文档。
2. 事实上，matlab 的发布者也 "works for functions"，特别是这里的第一点，应该被认为是一个错误而不是一个功能，或者最多作为一个微不足道的未记录的扩展。如果您查看 publish 命令的 matlab documentation，您会发现它需要一个文件名，而不是带参数的函数，并且文档仅讨论脚本而没有提及 'function' 兼容性。
3. 此外，即使您 确实 想将发布者用作 "documentation tool"，这对于函数来说也是违反直觉的在这种格式中，由于您需要提供参数以使发布者工作（不会在实际报告中显示），因此您需要一个显示中间计算的修改版本（与可能不会显示的普通版本相反） ), 该函数只是在报告末尾喷出一个难看的 ans= blabla 。如果您的最终目标是文档，那么最好为此编写一个定制脚本，显示正确的用法和示例，就像 matlab 在其 actual 文档中所做的那样。
说了这么多，是的，'cheat'您可以在发布的报告中包含函数代码，也就是说，在 Octave 中（从 R2016b 开始也是 matlab），可以在本地定义函数。仅包含函数定义的 .m 文件被解释为函数文件，但如果在函数定义之前还有其他 non-function-declaration 指令（注释除外），则它被视为脚本。因此，如果您发布此脚本，您将有效地获得包含功能代码的已发布报告：
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
（如果您对必须手动创建 'wrapper script' 不满意，您可以随时创建自己的包装函数来自动执行此操作）。
但是，matlab 和 Octave 发布者都是受限工具设计。正如我之前所说，它更像是一个 "quick report to show numbers and plots to your supervisor" 工具，而不是一个 "make nice documentation or professional reports" 工具。相反，我会投资于一个很好的自动化乳胶工作流程，看看用于显示代码的代码格式化工具，然后简单地将代码包装在一个脚本中，该脚本将输出生成一个文件，然后您可以将该文件导入乳胶。这听起来可能需要更多工作，但从长远来看，它更加灵活和强大，特别是因为格式化命令可能非常古怪且有限。
您可以使用 Octave Forge generate_html 包，它可以生成 html 个单独的函数。它主要用于生成 Octave Forge 包的文档，其默认值反映了这一点，但您可以添加任何您想要的样式。
此包将使用 Octave 中的 help 函数看到的相同帮助文本，这是文件中不是以 Copyright 或 Author 开头的第一块注释.你可以使用纯文本，但为了更好的格式，你可以使用 Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text 包括一个关于 Texinfo 语法的简短部分（实际的 Texinfo 手册可能有点让人不知所措）。
除了帮助文本，generate_html 包还识别 %!demo blocks 并生成一个包含演示代码的部分和它生成的输出，包括数字。
查看帮助文本和演示块在 Octave 中如何工作的最佳方法是检查源代码（正如@Andy 在评论中指出的那样）。例如，请参阅 source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page（注意演示块）。