Sandcastle - Documentation Compiler for Managed Class Libraries

New Post: Documenting XSLT files

SelormeyPaul — Mon, 07 Jul 2008 04:17:01 GMT

>>Greg: However, I do not know which of the XSD formats to use to integrate with sandcastle.
A simple way that will give you more control over the formating is to use the conceptual help topic,
in particular there is developerXmlReference topic type.
The developerXmlReference topic type currently as some issues but we could help you through the
Sandcastle Styles effort to resolve them.

>>Greg: ...future point I will be asking how to automate the production of the documentation.
I am also working/researching on automating the documentations of XSD. The priority is, however, low
(compared to the other work I am doing with Sandcastle through the Sandcastle Assist effort) mainly because
I do not have a project immediately requiring this. I could coordinate with you to find a reusable solution, if required.

Best regards,
Paul.

New Post: Documenting XSLT files

davedev — Mon, 07 Jul 2008 03:47:06 GMT

Hi Greg,

So you have XSLT files and you'd like to produce HTML documentation for them using Sandcastle?

The three presentation styles that come with Sandcastle are designed to build HTML documentation for application programming interfaces (APIs). Technically, they are designed only for managed APIs, but they can also be used to document other platforms as well, such as AJAX, for example.

If you want to document XSLT using the three built-in presentation styles then you must:

Generate a reflection.org file that uses the same schema that is used when reflecting into managed APIs. (The schema is located in Sandcastle's Schemas\Reflection folder.)
Generate an XML documentation file that uses the same schema as the compiler-generated XML documentation files that contain code comments.

I can't say whether XSLT will fit nicely into the existing schema that Sandcastle requires, but it's doubtful. In this case you'd have to roll your own solution by creating a custom presentation style.

Basically you'd have to write a program that could parse information about the structure and entities in an XSLT file and also any comments that you'd like included in the HTML documentation. From here the process would be similar to building documentation for managed APIs, although you'd have to use custom XSL files for your presentation style that could produce the HTML documentation from the XSLT "reflection" information. A custom Build Assembler configuation file would need to be created as well.

If you plan on trying this out I suggest starting with an existing presentation style by copying it to another directory. Then modify its parts, starting with the XSL transformations that produce the final HTML documentation. Once you determine what the final documentation should look like you can infer the schema for the XSLT reflection information and the XML documentation.

- Dave

New Post: Documenting XSLT files

galvord — Sun, 06 Jul 2008 23:51:30 GMT

I just downloaded and run a couple of quick proof of concept projects and really like what I saw. Of course as soon as a developer see something they like they want more.

A large portion of our project is in XSLT. I can write an XSLT to produce the documentation I want from the production XSLT files. However, I do not know which of the XSD formats to use to integrate with sandcastle.

I am sure that at some future point I will be asking how to automate the production of the documentation, but for know I would just like to know how to produce pieces that will fit in.

Thanks

Greg

New Post: How does MS build docs for .NET Framework?

SelormeyPaul — Fri, 04 Jul 2008 00:55:27 GMT

Hello Rastio,

>>Rastio: I'm using Sandcastle to build help for a large project (over 300 DLL's).
BTW, .NET performance guide recommends using less dll, but that is not the problem here.

>>Rastio: ...what is the best practice to build docs for large projects like .NET Framework?
Consider building several help topics not just "dll one by one", and if you want you can merge the
results. When carefully done, all the links will be well resolved and there is not need to worry
about large project. The MSDN itself is created from several help files, so you can do the same
instead of trying to build all in a go.
Both the HtmlHelp 1.x and 2.x viewers make it easy to view several files as if merged.

Best regards,
Paul.

New Post: How does MS build docs for .NET Framework?

rhodul — Wed, 02 Jul 2008 20:56:01 GMT

Hello,
I'm using Sandcastle to build help for a large project (over 300 DLL's).

I have put together an MSBuild project file to do the job. When I run this from command prompt everything is fine.

We use CruiseControl.NET to do our builds. Main MSBuild project on the build machine runs my Sandcastle MSBuild project to build the documentation after every build.
In this setup I always get OutOfMemoryException from BuildAssembler.exe.

So, I was thinking that I would not run MRefBuilder.exe on *.dll, but rather one by one all the way to HTML. But when building TOC reflection.xml is used, which is created in the process before and would only contain data from the last dll.

Can someone shed some light on what is the best practice to build docs for large projects like .NET Framework?

Thanks.
Rastio.

Here is my MSBuild project (or part of it):

<Target Name="ReflectionData"
          DependsOnTargets="PrepareWorkbench"
          Outputs="$(WorkingDir)\reflection.xml">
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\MRefBuilder.exe" "*.dll" /out:"reflection_base.xml" "/dep:$(NETSourceDir)\bin\*.dll"' />
    <Exec WorkingDirectory="$(WorkingDir)"
          Condition="'$(PresentationStyle)' == 'vs2005'"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\ApplyVSDocModel.xsl" /xsl:"$(ProductionTransforms)\AddFriendlyFilenames.xsl" "reflection_base.xml" /out:"reflection.xml" /arg:IncludeAllMembersTopic=true /arg:IncludeInheritedOverloadTopics=true' />
</Target>

<Target Name="Manifest"
          DependsOnTargets="ReflectionData"
          Inputs="$(WorkingDir)\reflection.xml"
          Outputs="$(WorkingDir)\manifest.xml">
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\ReflectionToManifest.xsl" "reflection.xml" /out:"manifest.xml"' />
</Target>

<Target Name="Html"
          Inputs="$(WorkingDir)\manifest.xml;$(WorkingDir)\reflection.xml"
          Outputs="$(DocumentationDir)\html\*.htm"
          DependsOnTargets="Manifest">
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\BuildAssembler.exe" /config:"$(MSBuildProjectDirectory)\sandcastle.config" "manifest.xml"' />
</Target>

<Target Name="Compile"
          Inputs="$(DocumentationDir)\html\*.htm;$(WorkingDir)\reflection.xml"
          Outputs="$(WorkingDir)\toc.xml"
          DependsOnTargets="Html">
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\CreateVSToc.xsl" "reflection.xml" /out:"toc.xml"' />

</Target>

<Target Name="HxS"
          DependsOnTargets="Clean; Compile"
          Inputs="$(DocumentationDir)\html\*.htm;$(WorkingDir)\toc.xml"
          Outputs="$(OutputDir)\$(HxSFileName).hxs">
    <Copy SourceFiles="@(HxsFiles)" DestinationFiles="@(HxsFiles->'$(OutputDir)\%(RecursiveDir)%(FileName)%(Extension)')"/>

    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template.HxF" DestinationFiles="$(OutputDir)\$(HxSFileName).HxF" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_A.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_A.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_B.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_B.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_F.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_F.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_K.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_K.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_N.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_N.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_S.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_S.Hxk" />

    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\CreateHxc.xsl" "toc.xml" /arg:fileNamePrefix=$(HxSFileName) /out:"$(OutputDir)\$(HxSFileName).HxC"' />
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\TocToHxSContents.xsl" "toc.xml" /out:"$(OutputDir)\$(HxSFileName).HxT"' />
    <Exec WorkingDirectory="$(OutputDir)"
          IgnoreExitCode="true"
          Command='"$(MSBuildProjectDirectory)\Help 2.0 Compiler\hxcomp.exe" -p "$(OutputDir)\$(HxSFileName).hxc"' />
</Target>

New Post: Sandcastle Language Filter does not stick when navigating to another page

SelormeyPaul — Wed, 02 Jul 2008 19:10:40 GMT

Hello,
I have just provided a fix for this issue. It is available as part of the issue tracker

Sticky Language Filter

Just download the attached file, script_manifold.js, rename the existing one in your

..\Presentation\vs2005\Scripts

folder, and place the updated version there.
Sandcastle already has the framework for supporting this in place, just needed some additions
to work with the HTMLHelp 1.x Viewer.
The changes are marked "CHM: Persistence.....", I think in three places.

Best regards,
Paul.

NB: Now that the Sandcastle is back let the fun begins....

Source code checked in, #11616

aram — Wed, 02 Jul 2008 16:46:48 GMT

Adding Source code for Sandcastle May 2008 Release (Version 2.4.10520)

UPDATED RELEASE: Sandcastle May 2008 Release (Version 2.4.10520) (May 29, 2008)

Wed, 02 Jul 2008 16:26:47 GMT

What's new in this version:
1. Sandcastle tools that will used for shipping Orcas SP1 RTM content.
2. Bug Fixes

Issues fixed in this version (Reported by Customers):
1. Sandcastle - scbuild is unable to handle dependencies in other directories
2. Sandcastle must properly escape VB keywords with square brackets
3. Sandcastle: <see> within <c> not shown
4. Sandcastle: A NullReferenceException threw by MRefBuilder.exe
5. Sandcastle: Add the FixScriptSharp transform to scbuild
6. Sandcastle: An Error of Transform (vs2005)
7. Sandcastle: Bug when doing a build that includes privates (/internal+) results in the non-nested class being ripped and the nested class being left
8. Sandcastle: BuildAssembler.exe raise an error when a root project node is included in the reflection.xml
9. Sandcastle: Change 2005 to 2008 in copyright info (prototype style)
10. Sandcastle: ChmBuilder /config switch
11. Sandcastle: chmbuilder drops a css file when handling <title />
12. Sandcastle: ChmBuilder.exe should create the Output Directory if it is not exist
13. Sandcastle: Conceptual Help: A better media art links
14. Sandcastle: Generic parameter is missed in Toc and Header Title of Generic Type
15. Sandcastle: inline seealso tag not working
16. Sandcastle: Js error raised when printing chm topics (prototype and vsorcas styles)
17. Sandcastle: make changes to build scripts to include environment variable ProgramFiles(x86) on 64 bits machine
18. Sandcastle: make changes to build scripts to include environment variable ProgramFiles(x86) on 64 bits machine
19. Sandcastle: MRefBuilder Generates Incorrect Member Signatures
20. Sandcastle: MRefBuilder ignores attributes on property getter/setter methods
21. Sandcastle: MRefBuilder namespace ripping feature bug
22. Sandcastle: need line break in C# Systax section (vs2005)
23. Sandcastle: Need to replace LowerCaseIdentifier method with CreateCamelCaseName
24. Sandcastle: Presentation issue list-tag as child of param-tag
25. Sandcastle: Presentation metadata transform bug - generates bogus type names
26. Sandcastle: Presentation Style Issues
27. Sandcastle: Public events are documented as protected in certain C++ classes
28. Sandcastle: Script# Presentation Style Issues
29. Sandcastle: seealso tags within an overloads tag not listed
30. Sandcastle: Support <inheritdoc/> tag
31. Sandcastle: The MSDN URLs generated by ResolveReferenceLinks2 are incorrect
32. Sandcastle: The root node is missing in manifest file

NEW POST: Sandcastle 'open source'?

pseale — Fri, 06 Jun 2008 14:26:37 GMT

The Sandcastle project is "open" to the Sandcastle team, not to the public. They could be doing the exact same thing they're doing now with a BSD or MIT license, both of which are approved OSI licenses.

So it does come back to CodePlex project source availability, even if you claim it's some sort of OSI thing. No project would be able to get away with this sort of thing on SourceForge, which has more stringent requirements.

Anyway, sorry for bloating up the discussion guys, I promise I'll stop; this discussion is clearly beyond the scope of a single CodePlex project. -Peter

NEW POST: Sandcastle 'open source'?

leppie — Fri, 06 Jun 2008 14:12:50 GMT

pseale wrote:
Leppie, you're misinterpreting OSI requirements. Or if you're not, then they're going to have to remove a great deal more licenses than just the Ms-PL.

Anyway, since you've said that you don't have an issue with Sandcastle or CodePlex, we can all now drop this discussion, excellent.

Final note: Reddit discussion is here: http://www.reddit.com/r/programming/info/6m64u/comments/ -Peter

I dont think so. The MsPL and MsRL (or MsLPL) are listed as open source licenses and certified by OSI (iow it adheres to the terms of the OSI definition). What is there not to understand about it? If they didnt want MsPL to be for OSS use alone, they should have never gotten it certified in the first place.

If you are referring to BSD-style licenses that does not explicitly specifiy source needs to be made available, show me a BSD licensed closed source project. In fact it seems you are confusing it with derivative works, which does vary greatly (the requirements) between licenses, but all are still open source.

Regards

leppie

NEW POST: Sandcastle 'open source'?

pseale — Fri, 06 Jun 2008 13:28:02 GMT

Leppie, you're misinterpreting OSI requirements. Or if you're not, then they're going to have to remove a great deal more licenses than just the Ms-PL.

Anyway, since you've said that you don't have an issue with Sandcastle or CodePlex, we can all now drop this discussion, excellent.

Final note: Reddit discussion is here: http://www.reddit.com/r/programming/info/6m64u/comments/ -Peter

NEW POST: Sandcastle 'open source'?

markdstafford — Fri, 06 Jun 2008 12:04:43 GMT

[Apparently, refreshing the page reposts whatever I posted last. My apologies for the repeats.]

NEW POST: Sandcastle 'open source'?

markdstafford — Fri, 06 Jun 2008 12:01:08 GMT

Russ,

I do understand the issue and will still dismiss it because even if the discrepancy were huge, it is still in our favor: Microsoft is releasing a tool that I can use, freely. It's a tool that they consider solid enough to compile the documentation for VS. The thing that bothers me (and probably many other business/corporate techies) the most, bar none, about open source is perfectly embodied in this thread: it seems as if it's permanently bogged down in legal quagmires. The reason I said to give it a rest is because no one here is going to bully Microsoft into releasing source. Either they will or they won't. If they won't, the best case scenario for most people in this thread is that they'll pull down the binaries and/or change the license for Sandcastle. Worst case scenario for Microsoft, you get the OSI to revoke their license. But what exactly have you achieved at that point? Have you stuck it to the man? Will you go to bed at night thinking, "Yeah, I really showed them!"

Peter,

I totally understand that expectations have been set, and I agree in principle with the fact that software on an open source-branded site should be open source. Where I diverge from the crowd here is in thinking that it's worth it to fight Microsoft on this. I'd cite the same rationale from the prior paragraph. It just seems like there are significantly more serious issues we could be going after. I truly believe the only possible appeasement for some people on this thread would be for Microsoft to pull down the binaries. (I'd restate that no one here can bully Microsoft into releasing source.) But Microsoft pulling down the binaries is just a headache for people like me for two reasons: first, it means that people like me have to move bookmarks, second, it means that Microsoft (who obviously puts a lot of money into Sandcastle but thought it might be useful to some of us smaller-company types) will be even more reticent in the future to release anything to benefit the community. If it costs them x in the first place to put this out (a cost they wouldn't have incurred if they hadn't released it at all), it will cost them x+1 or maybe even more to move it. As those costs mount, the likelihood of future freebies from Microsoft diminishes.

Most of all, I just get so frustrated when I read Slashdot/Engadget/Gizmodo and the most vocal people always seem to be anti-Microsoft. I have appreciated and continue to appreciate what I use from Microsoft and I don't want to see things like Sandcastle, or FxCop, or Source Analysis disappear. That's my rationale.

Mark

NEW POST: Sandcastle 'open source'?

duncan_bayne — Fri, 06 Jun 2008 06:27:31 GMT

leppie,

+1 to that. Maybe we should consider moving this - more important - aspect of the thread to a more appropriate forum? Otherwise the big picture (Ms-PL & OSI) is going to be obscured by the Sandcastle-on-CodePlex issue.

NEW POST: Sandcastle 'open source'?

leppie — Fri, 06 Jun 2008 06:18:42 GMT

Thanks for replying Anand.

a) The issue is not with SandCastle. It can relicensed.
b) The issue is not with CodePlex. The terms can be adjusted.
c) The issue is with MS-PL possibly not being a valid OSI license.

I have no concerns with a & b. Howver point c does affect me directly, and this needs to be sorted out.

An OSI license requires everything to be open source (else it cannot be licensed as OSS).

Cheers

leppie

NEW POST: Sandcastle 'open source'?

aram — Fri, 06 Jun 2008 05:52:21 GMT

Thank you Duncan for starting this thread, Leppie for personally writing to me and the rest of the community for providing valuable feedback. I am greatful for all the great community efforts, support around Sandcastle and the adoption rate. As I have mentioned in the past I will be happy to release the source of various presentation transforms, MAML schema, reflecton schema. They are already available to customers downloading Sandcastle. I am evaluating the options presented here carefully about the source code of the Production tools.

I ask your patience while I make every effort to address the options presented in this thread. I will get back to this thread with answers. Cheers.

Anand..
http://blogs.msdn.com/sandcastle

NEW POST: Sandcastle 'open source'?

reinux — Fri, 06 Jun 2008 04:58:57 GMT

The "molehill" is the Sandcastle issue. The "mountain" is Codeplex's perceived integrity. I don't think Microsoft is doing anything too "bad" here either legally or morally; that's not the problem. The problem is that Microsoft doesn't give a damn about its own reputation. And you know what? Sociologically speaking, it's becoming a big problem. Don't believe me? Check out the newest way to protect yourself from SQL injection attacks: just blame Microsoft! Can you imagine how many underqualified developers are evading responsibility with this trick?

Neither the people for or against leaving Sandcastle on Codeplex without source can deny that at the very least it's a decision that's raising eyebrows.

It's been made absolutely clear perhaps hundreds of times by now that one of Microsoft's biggest problems is its tendency to make itself misunderstood.

And it's absolutely appalling that Microsoft makes no effort to fix that.

NEW POST: Sandcastle 'open source'?

duncan_bayne — Fri, 06 Jun 2008 04:34:58 GMT

Russ,

You're right, & I stand corrected - the Ms-PL as it stands is not compatible with the Open Source Definition, because it does not mandate the release of source code. You can't get any clearer than this (my emphasis):

The program must include source code, and must allow distribution in source code as well as compiled form. Where some form of a product is not distributed with source code, there must be a well-publicized means of obtaining the source code for no more than a reasonable reproduction cost preferably, downloading via the Internet without charge.

Mark,

Personally, I think it's great that Microsoft has released Sandcastle. I'll probably use it for my project anyway given there is no OSS alternative, and do so gratefully. You are conflating three entirely separate issues:

Microsoft has done the development community a great favor by releasing a nifty tool for generating documentation.
Microsoft has done the development community a great disservice by diluting the value of OSI approval, and open source licensing in general.
Microsoft isn't playing by their own rules w.r.t. CodePlex.

We should all be praising Microsoft over point 1; since the well-publicized and frankly shameful death of NDoc there was no good solution for this problem and Microsoft has stepped up to the plate with a solution that's working for a lot of people. It's very clever from a business perspective too as it's closed a major gap between their platforms and others.

Personally, I don't care terribly much about point 3. Microsoft built CodePlex, they paid for it, and it's theirs to do with what they will if they're prepared to wear the potential PR costs of not playing by their own rules. It irks me, but not more than I'd be irked by not having access to Sandcastle.

However none of the above has any bearing on point 2. That is, Microsoft is attempting to muddy the waters with respect to what constitutes an open source license. I'm simply not inclined to believe that this is accidental; they perceive open source to be a threat to their business model, and have for a decade been developing & implementing strategies to combat it. Having a clearly non-OSS license approved by the OSI, and then releasing software under it to a nominally OSS site like CodePlex is an attempt to dilute the principles of OSS in a manner akin to trademark dilution. That may not bother you but it bothers the hell out of me - much more than the idea of not having Sandcastle bothers me.

That said, this isn't a terribly difficult issue to fix. All Microsoft needs to do is renounce their own OSI approval, or revise the Ms-PL license to require source release and re-license Sandcastle under some other license so that they can keep the source to themselves.

NEW POST: Sandcastle 'open source'?

markdstafford — Fri, 06 Jun 2008 03:35:40 GMT

Peter,

Mark

NEW POST: Sandcastle 'open source'?

markdstafford — Fri, 06 Jun 2008 03:07:40 GMT

Peter,

Mark