Sandcastle - Documentation Compiler for Managed Class Libraries

New Post: Missing shared content item

trailway — Thu, 16 May 2013 16:32:18 GMT

I am running the 1.9.7.0 help file builder on Windows 8 x64 and am seeing the following warning:

Warn: SharedContentComponent: [Overload:NetworkEngineer.Sdk.Inventory.NEPortClass.Search] Missing shared content item. Tag: 'includeAttribute'; Id:'altText_pub'.

I have not installed any SandCastle related bits other than those installed by the the guided installer. I am building a chm file using the help file builder with a VS2010 presentation style. I have also tried VS2005 but that did not seem to help.

I am guessing that there is something about the overloaded method which is causing the problem. The particular assembly uses the 4.0 .NET framework.

Closed Issue: Failed on localised classes/methods names [922]

DarrenParker — Thu, 16 May 2013 11:53:25 GMT

Sandcastle not support localised classes/methods/identifiers names in C# code.

For example:
public class МойКласс
{
public void МойМетод()
{
// ....
}
}

It success compiled by Visual Sudio (2003-2008), but Sandcastle is failed on XslTransform step.

Result of execution XslTransform:

"C:\Tools\Sandcastle\ProductionTools\XslTransform" /xsl:"C:\Tools\Sandcastle\ProductionTransforms\ReflectionToChmIndex.xsl" reflection.xml /out:"MyHelp.hhk"

Unhandled Exception: System.Text.EncoderFallbackException: Unable to translate Unicode character \u0441 at index 735 to specified code page.
at System.Text.EncoderExceptionFallbackBuffer.Fallback(Char charUnknown, Int32 index)
at System.Xml.CharEntityEncoderFallbackBuffer.Fallback(Char charUnknown, Int32 index)
at System.Text.EncoderFallbackBuffer.InternalFallback(Char ch, Char*& chars)
at System.Text.Latin1Encoding.GetBytes(Char* chars, Int32 charCount, Byte* bytes, Int32 byteCount, EncoderNLS encoder)
at System.Text.EncoderNLS.Convert(Char* chars, Int32 charCount, Byte* bytes, Int32 byteCount, Boolean flush, Int32& charsUsed, Int32& bytesUsed, Boolean& completed)
at System.Text.EncoderNLS.Convert(Char[] chars, Int32 charIndex, Int32 charCount, Byte[] bytes, Int32 byteIndex, Int32 byteCount, Boolean flush, Int32& charsUsed, Int32& bytesUsed, Boolean& completed)
at System.Xml.XmlEncodedRawTextWriter.EncodeChars(Int32 startOffset, Int32 endOffset, Boolean writeAllToStream)
at System.Xml.XmlEncodedRawTextWriter.FlushBuffer()
at System.Xml.XmlEncodedRawTextWriter.WriteRawWithCharChecking(Char* pSrcBegin, Char* pSrcEnd)
at System.Xml.XmlEncodedRawTextWriter.WriteRaw(String data)
at System.Xml.TextEncodedRawTextWriter.WriteString(String textBlock)
at System.Xml.Xsl.Runtime.XmlQueryOutput.WriteString(String text, Boolean disableOutputEscaping)
at System.Xml.Xsl.Runtime.XmlQueryOutput.WriteString(String text)
at <xsl:template name="createIndexEntry">(XmlQueryRuntime {urn:schemas-microsoft-com:xslt-debug}runtime, IList`1 text, IList`1 file)
at <xsl:template match="/">(XmlQueryRuntime {urn:schemas-microsoft-com:xslt-debug}runtime, XPathNavigator {urn:schemas-microsoft-com:xslt-debug}current)
at Root(XmlQueryRuntime {urn:schemas-microsoft-com:xslt-debug}runtime)
at Execute(XmlQueryRuntime {urn:schemas-microsoft-com:xslt-debug}runtime)
at System.Xml.Xsl.XmlILCommand.Execute(Object defaultDocument, XmlResolver dataSources, XsltArgumentList argumentList, XmlSequenceWriter results)
at System.Xml.Xsl.XmlILCommand.Execute(Object defaultDocument, XmlResolver dataSources, XsltArgumentList argumentList, XmlWriter writer, Boolean closeWriter)
at System.Xml.Xsl.XmlILCommand.Execute(XmlReader contextDocument, XmlResolver dataSources, XsltArgumentList argumentList, XmlWriter results)
at System.Xml.Xsl.XslCompiledTransform.Transform(XmlReader input, XsltArgumentList arguments, XmlWriter results)
at Microsoft.Ddue.Tools.XslTransformer.Main(String[] args)
Last step completed in 00:00:19.2783

BUILD FAILED: Unexpected error in last build step. See output above for details.

Reviewed: Sandcastle-June 2010 Release (Version 2.6.1062.1) (Apr 25, 2013)

evolvedmicrobe — Thu, 25 Apr 2013 17:22:34 GMT

Rated 2 Stars (out of 5) - No documentation or samples....

New Post: generate doc. from website

EWoodruff — Tue, 23 Apr 2013 19:12:08 GMT

Its not enough just to modify the Web.config file. It must be able to find the web code provider assembly. That can be accomplished most easily by placing it in your project's .\bin folder as noted in the documentation. Also, since you appear to be using VS 2012, you'll need to update the compiler version value in the providerOptioon element to either "v4.0" or "v4.5" depending on which version of the framework you are targeting.

The VB.NET code provider doesn't always import all of the necessary namespaces either. As noted in the Usage Notes and Known Issues section of the documentation, you may need to add extra "/imports:XXXX" options in the compilerOptions attribute to define the missing namespaces. The other option is to add the necessary Imports statements to the code if they aren't there already.

Also, please note that this project has been discontinued and may not be monitored as frequently. For future questions concerning Sandcastle or SHFB, post them over on the Sandcastle Help File Builder project's discussion page. Thanks.

Eric

New Post: generate doc. from website

alebencz — Tue, 23 Apr 2013 16:16:23 GMT

I am trying to generate documentation for a WebSite, but, I don't have a project, in other words, I just go in Visual Studio and I Open a WebSite, I can't generate the XML documentation from this web project style:

And, I see in [that][2] documentation I need to put this:

      <system.codedom>
        <compilers>
          <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb"
            compilerOptions="/docpath:C:\Publish\Docs"
            type="EWSoftware.CodeDom.VBCodeProviderWithDocs,
                  EWSoftware.CodeDom, Version=1.1.0.0, Culture=neutral,
                  PublicKeyToken=d633d7d5b41cbb65">
            <providerOption name="CompilerVersion" value="v2.0"/>
          </compiler>
        </compilers>
      </system.codedom>

Ok, but when i put this in my web.config, and When I try to build, the compiler return a lot of errors, like that:

    error BC30451: 'DDtoCC' is not declared. It may be inaccessible due to its protection level.
    0error BC30451: 'HojetoCC' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'CCtoDD' is not declared. It may be inaccessible due to its protection level.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30451: 'DataDiff' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'AddDiastoCC' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'AddDiastoCC' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'QueryDB' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'AddDiastoCC' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'QueryDB' is not declared. It may be inaccessible due to its protection level.
    error BC30451: 'Truncate' is not declared. It may be inaccessible due to its protection level.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlDataReader' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30451: 'QueryDB' is not declared. It may be inaccessible due to its protection level.
    error BC30002: Type 'SqlConnection' is not defined.
    error BC30002: Type 'SqlCommand' is not defined.
    error BC30451: 'HojetoCC' is not declared. It may be inaccessible due to its protection level.

And, When I remove this, the code is compiled normaly ;x

And, I have tried to create a web project whit this code, BUt, I got the same error..
How I can generate the documentation of this web syte project ??

New Post: Custom Presentation Style with custom header layout

EWoodruff — Mon, 22 Apr 2013 21:10:40 GMT

The logo can be a permanent part of the style if you like. It's implemented in parameters in the existing styles since many people don't want a logo. The parameters are a convenience as then the implementation is part of the XSL transformations and the build tools do not need any special knowledge about how the presentation style is implemented beyond being given a set or parameters to pass in if used.

The header layout is mostly controlled by the XSL transformations. You'll need to modify them in order to alter how the header is rendered. The shared content items are mainly used to localize the text elements such as labels and link text.

Also, please note that this project has been discontinued and may not be monitored as frequently. For future questions concerning Sandcastle or SHFB, post them over on the Sandcastle Help File Builder project's discussion page. Thanks.

Eric

New Post: Custom Presentation Style with custom header layout

moleone — Fri, 19 Apr 2013 14:38:05 GMT

hi,

Version Compiler: 2.7.3.0
Version Builder: 1.9.7.0

I'm trying create acustom presentation style as described in the help. This results in two questions:

Can I bind the logo to the style, so I do not have to create an Icons\Logo.gif in each Sandcastle project and must enter it under the project properties?
What is the right way to completely overwrite the header layout. At first I thought I could do this with the MyStyle\Shared Content strategie. However, there seems to influence only part of the header.

And let me say: I'm new in using Sandcastle, but this tool inspires me a lot.

best regards
Mole

New Post: WCF Web Services and REST API Documentation.

YoGoUrT — Wed, 17 Apr 2013 19:31:14 GMT

Hi both of you. I'm also looking to document a web service and I would like to know if you found a solution to your problem ?

New Post: Link API Members from Conceptual

EWoodruff — Thu, 28 Mar 2013 19:40:21 GMT

If you want a list of all classes in a namespace, the namespace ID will work as noted above. If you want a list of all namespaces, the R:Project_[ProjectName] ID should do it. Replace "[ProjectName]" with the name from your SHFB Project's Help Name property with any spaces replaced by underscores.

If your intent is to list classes nested within some other arbitrary class, there isn't a way to do that since the presentation styles don't generate anything for nested classes within another class. Each class gets its own top-level entry in the TOC and the namespace list pages even if it's nested within another class. The nested classes are prefixed with their parent class's name.

Eric

New Post: Link API Members from Conceptual

TeaMaster — Thu, 28 Mar 2013 19:35:18 GMT

I meant something like this:

<codeEntityReference qualifyHint="false">Classes.T:NameSpace.Class</codeEntityReference>

But it doesn't seem to work

New Post: codeEntityReference - Change target online MSDN .Net Framework version

EWoodruff — Thu, 28 Mar 2013 19:34:35 GMT

That isn't currently supported. It's something I plan on looking into in a future release of the Sandcastle tools.

Also, please note that this project has been discontinued and may not be monitored as frequently. For future questions concerning Sandcastle or SHFB, post them over on the Sandcastle Help File Builder project's discussion page. Thanks.

Eric

New Post: Link API Members from Conceptual

EWoodruff — Thu, 28 Mar 2013 19:32:03 GMT

You can use the namespace ID to go to its page (N:NamespaceId). You can use the Entity References Window in the SHFB standalone GUI or Visual Studio package to add references to API members such as namespaces, types, and methods, etc. Select the Code Entities option in its drop down. It won't list the group entries such as AllMembers though since they are added at build time by the presentation style if it supports them.

Eric

New Post: codeEntityReference - Change target online MSDN .Net Framework version

Mythran — Thu, 28 Mar 2013 17:57:36 GMT

I have the following codeEntityReference:

<codeEntityReference>
    P:System.Web.Configuration.HttpCapabilitiesBase.Id
</codeEntityReference>

When compiled, I can click on the link and it opens the online MSDN library...but always selects the most recent version of the framework, instead of the targetted version! Is there a way for me to set the correct version so when the link is clicked, it will automatically target a different framework version?

Thanks! :)

New Post: Link API Members from Conceptual

TeaMaster — Thu, 28 Mar 2013 13:37:18 GMT

thanks!

The same way. How could I get the list of classes only?

New Post: Link API Members from Conceptual

EWoodruff — Wed, 27 Mar 2013 19:32:50 GMT

You just need to get the ID in the correct format:

<codeEntityReference qualifyHint="false">AllMembers.T:NameSpace.Class</codeEntityReference>

<codeEntityReference qualifyHint="false">Methods.T:NameSpace.Class</codeEntityReference>

Also, please note that this project has been discontinued and may not be monitored as frequently. For future questions concerning Sandcastle or SHFB, post them over on the Sandcastle Help File Builder project's discussion page. Thanks.

Eric

New Post: Link API Members from Conceptual

TeaMaster — Wed, 27 Mar 2013 17:31:34 GMT

Hi! I'm trying to link the "All methods"/members page of a class from the conceptual.

*The one that says The "class" type exposes the following members.

Something like this:

<codeEntityReference qualifyHint="false" autoUpgrade="true">Methods:NameSpace.Class</codeEntityReference>

New Post: Document to use SandCastle

mightymuke — Fri, 15 Mar 2013 13:09:14 GMT

Please note that this project has been discontinued and may not be monitored all that frequently. For documentation and other information concerning Sandcastle or SHFB, check out the Sandcastle Help File Builder project.

New Post: Document to use SandCastle

pradeepk85 — Fri, 15 Mar 2013 12:21:15 GMT

Hi,

I am new to SandCastle and not able to use this tool. Can anyone help me how to use this tool or any documentation present to use the same.

Thanks,
Pradeep

Commented Issue: Generation of API documentation for inherited members when DocumentInheritedMembers is false [12784]

EWoodruff — Fri, 01 Feb 2013 20:33:05 GMT

We are using Sandcastle to generate our API Reference, but we do not want to include inherited members. That's why we have set the DocumentInheritedMembers to false. But for some of our classes we still get inherited members in the documentation. After some testing we found that the issue occurs when the child class and the parent class have similar names. And by similar I mean that the parent class has the same name as the child, but with some more letters at the end. For example:
```
public abstract class ChildClassBase
{
public int PublicProp1 { get; set; }
public string PublicProp2 { get; set; }
private int privateProp1 { get; set; }
private string privateProp2 { get; set; }
}

public class ChildClass : ChildClassBase
{
public string ChildProp1 { get; set; }
}
```
In the documentation of ChildClass you will see descriptions for ChildProp1, PublicProp1 and PublicProp2. The same is valid if the parent class is named ChildClassTest, ChildClassT, etc. But if I rename the parent or the child, for example ChildSubClass and ChildClassBase, the documentation for ChildSubClass will hold only information about ChildProp1.
Just one more thing to add - all visibility properties in our project are set to false.

The issue is reproduced with Sandcastle 1.9.5 and 1.9.6 (I haven't tested it in older version.
Comments: ** Comment from web user: EWoodruff **

The code that strips out inherited members does an XPath starts-with() comparison to find them. I added a period to the end of the type name to limit what it finds to just those members belonging to the specific type rather than those matching the prefix which was too inclusive. It's fixed for the next release of SHFB.

Also, please note that this project has been discontinued and may not be monitored as frequently and I can't close work items here. For future questions or issues concerning Sandcastle or SHFB, post them over in the [Sandcastle Help File Builder](http://shfb.codeplex.com) project. Thanks.

Created Issue: Generation of API documentation for inherited members when DocumentInheritedMembers is false [12784]

RosenVl — Wed, 30 Jan 2013 09:28:14 GMT