标签: sandcastle

微软在发布Sandcastle的CTP/Beta版本时杀死了NDoc,我很少看到有关沙堡的可用版本的新版本的信息(例如,带有集成的UI).最新的发布是2008年5月的发布.Sandcastle是一个死的项目还是将它包含在Visual Studio 2010中？

假设我有一个方法如下:

    /// <summary>
    /// Here I want to reference the parameter <see cref="personId"/>.
    /// </summary>
    /// <param name="personId">
    /// The person id.
    /// </param>
    /// <returns>
    /// The <see cref="Person"/>.
    /// </returns>
    public Person GetPerson(int personId)
    {

    }

当我使用sandcastle发布我的xml文档时,cref:

<see cref="personId"/>

转换为[!:personId].

Sandcastle的警告是:

'未知参考链接目标'

有什么建议？谢谢.

我的团队负责为我们编写的大型系统开发API.我们需要提供示例代码,以便使用我们的API的其他开发人员可以学习如何使用它.我们一直在使用xml文档注释来记录代码.例如.

/// <summary>Summary here</summary>
/// <example>Here is an example  <code>example code here</code> </example>
public void SomeFunction() 

然后我们使用Sandcastle并构建我们需要的帮助文件(chm和在线网站).

当示例代码不起作用时,这是非常尴尬的,这通常是因为某些功能已更改或一个简单的错误.

有没有人做过这样的事情,还配置了单元测试来运行示例代码,以便知道它们在构建期间工作？

我正在寻找一个满足这些要求的帮助/文档生成工具:

• 它应该支持c#编译器生成的xmldoc注释或者(甚至更好)直接支持sandcastle
• 它应该支持导入MS Word文档.
• 它应该支持创建从概念文档到源代码生成的参考文档的链接.
• 如果它支持MS Word中的概念性文档创作,那就太好了

更多细节.我的项目是.NET的框架/库.它有几个VS解决方案,共有超过50个C#项目.首先,我想从我的项目的源代码生成帮助(将来chm&help2&help3).我将该文档称为"参考文档".Sandcastle(特别是使用SCFB)可以非常好的方式做到这一点.但是(我想这是非常常见的情况)我有一些框架/库的附加文档.该文档是在MS Word文件(5-10文件)中.我将该文档称为"概念文档".我想用概念文档和参考文档(如MSDN)生成一个可靠的帮助系统.我希望帮助的概念部分包含链接(URL),它引用框架/库中每个.NET类型名称的帮助的引用部分.(显然,任何帮助系统最终都只是HTML).

问题是如何创建这些链接.MS Word文件对C#xmldoc一无所知.Sandcastle不支持Word文件.所以我必须采取一些帮助创作工具(HAT).到目前为止,我找不到任何不适合我的工具.如果有任何帮助,我将非常感谢!

所有工具的绊脚石都是链接自动创建.我想在生成期间自动创建链接(可以在构建服务器上进行).为何自动？因为它允许轻松重命名类型.例如.我在概念文档中有一些文本:"用于访问请求处理上下文使用静态属性Current of XOperationContext type".这里XOperationContext是一个类型名称.我希望它成为XOperationContext类在结果帮助系统中的规范的链接(URL),没有任何重大的努力.我想在Word中标记它(可能安装了一些HAT的插件),或者在HAT的编辑器中标记为"如果可能的话,使这个单词链接".在生成期间,如果存在具有此类名称的类型名称,则每个这样的单词将成为链接.

我知道这些工具:

• Toolsfactory Doc-o-Matic(现在使用)
• Innovasys DocumentX和HelpStudio
• ComponentOne Doc-to-Help

Doc-o-Matic支持链接自动创建.真的自动.它尝试为PascalCase中的每个单词创建一个链接 - 非常出色.但它不支持MS Word.Innovasys和ComponentOne的软件不支持自动创建链接.Innovasys的软件不支持MS Word(我不确定100%这个).

我试图在Innovasys和ComponentOne的论坛上提问.到目前为止没有运气.Innovasys的软支持场景就像我一样:在单独的工具中创建概念文档 - HelpStudio,并使用其他工具从源代码生成帮助 - DocumentX.但是没有能力自动创建链接并导入MS Word文件.

所以,请分享你对这个共同任务的过期(我确信它应该是常见的).

请告诉我,如果我没有从英语语法的角度正确解释我的想法,我会再试一次.

我在哪里可以下载Microsoft HTML Help 2编译器(或绑定SDK)？我想使用Sandcastle帮助文件生成器从我的编程项目生成HTML 2文档,Sandcastle Guided Installation向导指示我下载该组件.

关于从Sandcastle主页获取的HTML 2的摘录:

HTML Help 2.x输出包括一组有效的集合文件和一个H2Reg.exe配置文件,以简化帮助文件的部署和集成到现有集合(如Visual Studio使用的集合)中.

我正在尝试使用sandcastle帮助文件构建器生成文档.在沙堡中构建项目时,我收到以下错误.

MRefBuilder : error : Unresolved assembly reference: Microsoft.Owin (Microsoft.Owin, Version=2.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35) required by Microsoft.AspNet.Identity.Owin [C:\Users\inkosah\Documents\Help\Working\GenerateRefInfo.proj]
Last step completed in 00:01:19.4610

有人可以帮我解决这个问题吗？我也尝试将它单独添加到沙堡中的项目引用但没有帮助.

我对SandCastle的输出非常满意,但是我还想在HTML输出中包含一些搜索功能,这可能吗？

我真的很喜欢在我的项目中使用SandCastle生成的帮助文件...是否有适用于SandCastle的Visual Studio 2010插件,或者是直接与Visual Studio集成的另一个好的替代程序？

我有这个方法,我试图生成文档.

    /// <summary>
    /// This method demonstrates taking a Func as argument and perform that action(Func) on a list of strings.</summary>
    /// <param name="listOfStrings"> ... </param>
    /// <param name="ActionToPerformOnEach"> ... </param>
    /// <returns>Returns an <see cref="IEnumerable{String}" /> which has elements that resulted due to the Func action </returns>
    public static IEnumerable<String> ActOnListWithFunc(List<string> listOfStrings, Func<string, string> ActionToPerformOnEach) {
        foreach (string s in listOfStrings) {
            string actedString = ActionToPerformOnEach(s);
            yield return actedString;
        }
    }

这会生成这样的文档(仅显示返回值部分)

Return Value
Type: IEnumerable<String>
Returns …

我试图在我使用Sandcastles生成的CHM文件中包含代码示例.这是我到目前为止:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <example>
/// <code>
/// public int Test
/// {
/// private int test { get; set }
/// private int test2 { get; set; }
/// public int findE()
/// {
/// if(test == test2){
/// return Console.WriteLine("Variables are Equal")
/// }
/// else{
/// return Console.WriteLine("Variables are not equal")
/// }
/// }
/// }
/// </code>
/// </example>

这非常混乱,我宁愿在我的.cs文件中没有这个代码.有没有办法将此示例代码放在单独的.cs文件中,并以某种方式在注释中引用它？所以相反,我会有这样的事情:

/// <summary>
/// Lorem ipsum.
/// </summary>
/// <reference src="mycode.cs"> …