标签: documentation-generation

我正在使用GitHub页面的"自动生成器",我发现它只生成一个index.html和其他Web资源.

如果我想从其他降价文件生成多页网站,它是如何工作的？

Sphinx是一个Python库,可以从一组ReST格式的文本文件生成很好的文档.不是用于全文搜索的工具

我也完全了解doxygen/phpdoc工具.我想弄清楚是否有办法使用Sphinx来记录php项目？甚至任何其他非python语言？

http://sphinx.pocoo.org/

我遇到了Doxygen识别命名空间和模块的问题.我认为问题围绕着是\addtogroup在命名空间内还是在命名空间之外.

示例1,在命名空间之外:

/*!
 *  \addtogroup Records
 *  @{
 */

//! Generic record interfaces and implementations
namespace Records
{

  //! Describes the record interface  
  class Interface;

} // End namespace Records

/*! @} End of Doxygen Groups*/

示例2 - 在命名空间内

//! Generic record interfaces and implementations
namespace Records
{
/*!
 *  \addtogroup Records
 *  @{
 */


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Records

我希望它namespace Records出现在Doxygen Namespaces …

我正在寻找一个从我的VS2010 XML文档创建HTML /帮助文件的好工具.我找到了一些商业工具,比如

• .Net文档工具
• VSDocman

我相信还有更多,我只列出这两个例子.还有简单的XSLT样式表,可以将XML转换为HTML文档.

您在使用什么,例如是否有免费工具进行转换,可能是插件.只是为了澄清,基本上我找到了两种工具:

1. 以不同的目标格式转换XML文档文件的那些,这就是我正在寻找的.
2. 帮助我在源代码中生成XML文档的工具.这不是(!)我在寻找的东西.

谢谢你的帮助.

Sandcastle/SHFB组合效果很好.感谢所有帮助过的人.

一些评论:

1. NDoc似乎已经过时,最近的更新是从2005年开始的.这就是我跳过这个的原因.
2. 类似的线程,也非常详细,可以在这里找到:如何将C#Xml Doc-Comments变成有用的东西？谢谢你的暗示!
3. Sandcastle有一些来源,我找到的最新版本位于:http://sandcastle.codeplex.com/
4. 为了生成MsHelp2我不得不安装VS 2008 SDK包含hscomp.exe.有一个版本1.0和1.1,据我所知,版本1.0包含编译器.有关详细信息,请参阅Helixsoft和Social MSDN.
5. 在我的情况下,生成的WebHelp无法与Chrome正常工作.它总是重新加载index.html页面.
6. 此处的主题显示如何将命名空间信息添加到sandcastle文档中.
7. 截至2012年11月的更新:对于我使用Doxygen的小型项目- 我发现它更容易配置.

我希望使用Swagger记录我的restful接口.问题是我不想通过注释我的代码来自动生成我的文档.基本上我不想将我的内部数据模型耦合到接口公开的虚拟数据模型.看来我可以让我的服务器提供一个Resources.json文件,然后为每个资源处理程序提供相应的JSON文件.但是,当我尝试这个时,我试图定义JSON正确的语法并提供正确的HTTP头响应字段时遇到了很多小问题.

有没有人用这种方式使用Swagger？有人有一些文件或例子吗？我能找到的所有内容都只是使用客户端库为您生成内容.

我正在研究共享的Matlab代码,我们希望在本地网络中共享生成的文档作为可搜索的HTML文档.

我知道以下生成文档的方法:

1. 将转换器写入类似C++的文件.这是在使用Doxygen with Matlab(2011年最后更新)和mtoc ++(最后更新2013年)中完成的.然后由Doxygen解析类似C++的文件.
2. 使用Python的sphinxcontrib-matlabdomain生成HTML文档.
3. 使用m2html也是第三方解决方案.
4. 此问答中列出了其他选项:一,二和三.

Mathworks不支持所有可能性.所有可能性都需要我提到自己的函数参数.他们没有分析代码,Doxygen是为Java做的:

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

我听说过Matlab的publish()函数,但我从未在上述意义上看到过它.

问题:Mathworks生成Matlab HTML文档的方法是什么.代码本身可以分析吗？我可以使用提供给Matlab输入分析器的信息吗？请在评论中提及您的个人偏好.

例:

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

我正在使用Doxygen和一些嵌入式C源代码.给定一个.c/.h文件对,你是否将Doxygen注释放在函数原型(.h文件)或函数定义(.c文件)上,还是在两个地方都复制它们？

我遇到一个问题,当我在一个地方而不是另一个地方记录时,Doxygen会警告缺少评论; 这是预期的,还是我的Doxygen搞砸了？

我还没有找到一个合理的工作流程来构建包和编写他们的文档.

我希望尽可能多地自动生成流程(和文档).

显而易见的方法是使用package.skeleton创建基本包文件,然后以编程方式覆盖DESCRIPTION文件和Rd文件.这样做的问题在于您丢失了自动生成的字段,确保您记得记录所有正确的参数.

我想知道你如何构建包和编写文档.有没有可用的工具使这个过程更容易？(roxygen看起来像是为这类东西而设计的;有没有一个很好的教程呢？还有其他选择吗？)

我是操作包的作者,其中包括示例代码.我想这个示例代码是hscolored并与由Haddock生成的API文档一起安装.

我可能必须使用自定义Cabal构建类型并为Haddock阶段创建用户钩子.但是,我从未设法做到这一点.因此,我的问题是:

如何将完整模块作为示例代码包含在Haddock中？

你能给出一个Cabal用户钩子的例子,它将hscolor应用于另一个源代码文件example.hs并将结果与​​生成的Haddock文档连接起来吗？

我们都有记录代码的好习惯,对吧？

如今,代码内文档本身就有一种语法.它几乎就像一种编程语言.问题是:

• 存在多少(多少)文档语法规范？
• 是否有标准的文档语法？
• 谁在定义这个标准？是否有一个官方委员会或机构(就像有一个定义C++标准)？
• 或者"doxygen"成为事实上的标准？

很难不听说doxygen.在我参与的每个开源软件项目中都提到过.但是,看看官方的doxygen网站,doxygen定义任何规格都是显而易见的! 当我读到"它可以帮助我的方式"时,我得到的印象是,doxygen只是一个提取代码内文档并将其呈现在漂亮的HTML页面中的软件.看看doxygen首页,我甚至认为doxygen可以使用第三方规范中定义的任何文档语法并将其解压缩并输出为HTML.

而且,有趣的是,doxygen的网站,并没有利用这个词doxygen的,就好像它是没有品牌的软件,而是一个普通名词(当然,是吗？)

什么是doxygen真的吗？

• 解析引擎？
• HTML渲染引擎？
• 一个可以被第三方软件用来呈现自己的文档的库？
• 文档语法(事实上)规范？
• 上述所有的？

我对doxygen和其他代码解析器之间的关系特别感到困惑,比如ANTLR,boost-spirit,Ragel ......

例如,什么是doxygen可以做的,ANTLR不能,而ANTLR可以做氧吗？

另外,看看Drupal项目.他们有:

• 他们自己的API模块是" Doxygen文档生成器规范子集的实现 ".
• 他们自己的语法解析器模块(添加到上面的列表,与doxygen本身,ANTLR等等).
• 他们自己的API网站运行上述两个模块,提供Drupal in-code"doxygen"文档.

因此,采用C++类比,似乎"doxygen"这个词过载并且在不同的上下文中意味着不同的东西.

在Drupal项目中,"doxygen"并不是指软件,而是指文档语法的(标准？)规范,尽管如上所述,doxygen网站本身的头版并未声称是这样的事情!

所以,我的离题是:

还有其他文档语法规范吗？