A few faqs about Sandcastle

I’m super excited about the response to the Sandcastle CTP launch. Much of the response has been positive, and folks have asked some great questions. Let me try to address a few of the common questions people have about the site:

Where can post Sandcastle related questions?
Please post all Sandcastle related questions and discussions at https://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1. Please use Sandcastle: at the beginning of your questions when posting questions at this forum. You can also send feeback and bugs to sandchlp@microsoft.com.

Is Sandcastle used by Microsoft for their API documentation?
Yes. This CTP version has a new architecture and has reduced the .Net Framework build time from 10 plus hours during VS 2005 ship cycle to 30 minutes. For the current CTP release the focus was on scalability and performance.

When can we get better documentation?
Scott Hanselman's provides his honest opinion about this CTP release documentation here. Better documentation with architectural overview is on it's way and I will post them shortly.

Will there be an SDK for Sandcastle?
Most likely; Sandcastle will be a part of VS SDK release. For the current CTP release the focus was on scalability and performance.

Will Sandcastle have a GUI and viewer?
Not for Version 1.0. Several customer written GUIs are available at https://www.sandcastledocs.com.

Will there be another CTP release?
Yes; We plan to few CTP releases before Sandcastle 1.0 RTW.

How can change author comments from comments.xml to a different file name?
Please look at the following section in sandcastle.config file:

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll">
<index name="comments" value="/doc/members/member" key="@name" cache="100">
<data files="comments.xml" />
<data files="C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\*.xml" />
</index>

The comments.xml in sandcastle.config file can be replaced with any other file name such as foo.xml or multiple xml files with *.xml.

How can I use MrefBuilder with /dep option?
The dependencies can be at a separate folder called dependency.
MrefBuilder can be invoked with the /dep switch as below:

MRefBuilder foo.dll /out:reflection.org /dep:dependency\*.dll

MrefBuilder also takes wildcards like the following:

MRefBuilder dll\*.dll /out:reflection.org /dep:dependency\*.dll

That is, if I put all the assemblies I want to reflect over in a directory named dll and tell it to get them from there.

Is it possible to include private members in the output from Sandcastle? If not will this be added as an option on a later CTP?
It's not possible to document private members using the July CTP version of Sandcastle. However we plan to add couple switches to the syntax invocation for MRefBuilder is as follows:

MRefBuilder.exe dll /dep:dep /out:out /internal-

The Boolean /internal option enables documentation of private APIs to be produced for the internal consumption of development teams.

Does Sandcastle resolve reference to GAC DLLs?
We do not resolve references to GAC. You have to use the /dep switch and refernce those dependent assemblies. Resolving refence to GAC is a feature request that we did not get to in this CTP release.

Can the build steps be automated?
Yes. We will be releasing automated scrips in our future releases. Mikael Söderström has a "Sandcastle Helper" here, Ashley van Gerven has a batch script availabe here and Scott Hanselman's has power shell script availabe here.

 

That's all for now...more coming soon. I'm trying to read as many blog posts and comments as possible to collect feedback and questions about the site, but if you have particular questions you'd like to make sure I address, please post them here!

Anand..