Documenting Code With Sandcastle

Expertise

Features

Documenting Code With Sandcastle

A Work in progress, expect this to be cleaned up soon.

We are coming to the end of the project here at work so needless to say all the documentation has to be handed over, including the API for the code base.
As we using .Net 3.0, Ndoc cant be used, so its replacement sandcastle was our obvious option. Sandcastle being still a CTP is pretty clumsy to use, so here is some tips to get you going.

Firstly check out the Gui or batch tools out there, some of them are pretty good. Check the codeplex stuff and SandcastleGUI .
Unfortunately this (specifically SandcastleGUI) wouldnt work for me as it tries to find DLLs that may be referenced even if not used (this may point to redundant ref in our code). As time was not on my side i decide to just run with the default console implementation.

...Anyway some tips.
Put all your Dll's in one directory. Even if this means copying them all into a holder directory for the means of the documentation exercise. This includes anything that the dll's may reference. Normally this is the case anyway, however with distributed systems, and gacs, and what not, it isnt always the case.

Assuming you install sandcastle in "C:\Program Files\Sandcastle" the below script will create your help file.

"C:\Program Files\Sandcastle\ProductionTools\MRefBuilder.exe" alpha.dll beta.dll gamma.dll /out:reflection.org "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\AddFriendlyFilenames.xsl" /out:reflection.xml "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToManifest.xsl" reflection.xml /out:manifest.xml call "C:\Program Files\Sandcastle\Presentation\vs2005\copyOutput.bat" "C:\Program Files\Sandcastle\ProductionTools\BuildAssembler.exe" /config:"C:\Program Files\Sandcastle\Presentation\vs2005\Configuration\sandcastle.config" manifest.xml "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmProject.xsl" reflection.xml /out:Output\test.hhp "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\createvstoc.xsl" reflection.xml /out:toc.xml "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\TocToChmContents.xsl" toc.xml /out:Output\test.hhc "C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe" /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmIndex.xsl" reflection.xml /out:Output\test.hhk "C:\Program Files\HTML Help Workshop\hhc.exe" output\test.hhp pause

The only change you would then need for this script is to put the names of the DLL's you actually want to document (ie replace alpha.dll beta.dll gamma.dll with your dll(s))... you may want to do this before running the batch file ;)

Copy and paste the script below into a text file make the dll name change on the first line sand save it as a batch file eg "documentation.bat". Save it in the same folder as your dll's and run it (click it).

This will give you an ultra generic help file, ala visual studio 2005 and all the rubbish .net 2.0 help files when it first came out.
I personally played with the xsl file to add in images etc to customise it a bit. i'm sure there are better ways to do it but i'm not spending any more time on some thing that i doubt anyone will ever read.
If you want them all spruced up, you probably want to check out the tools mentioned above.

EDIT: Sorry I fogot to mention that I dont name all of my XML Comment files "comments.xml"!
I usually name them the same as my dll's with an xml extension eg alpha.dll has the comment file alpha.xml . This means I had to make a change in the sandcastle config file (" C:\Program Files\Sandcastle\Presentation\vs2005\configuration\sandcastle.config " in my case) line 63 from
< data files=".\comments.xml" / >
to
< data files=".\*.xml" />
to allow for all of the xml files to be a part of the help (which is what you really want now isn't it!).
Just make sure there are only comment XML files (ie no other data xml files) in the directory or i guess it could go pear shaped. Alternatively perhaps name them *.dll.xml and use that as the data file filter.
EDIT 2:
To change the lines at the top & bottom of the main pages
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
&

Send comments about this topic to Microsoft.

Edit the shared_content.xml file found below.
C:\Program Files\Sandcastle\Presentation\*\Content\shared_content.xml

To change the foot note that defaults to “Send comment about this topic to Microsoft” to something more appropriate
Go into C:\Program Files\Sandcastle\Presentation\vs2005\Content\Shared_Content.xml” and change the footer that begins in line 118. The third parameter in the javascript function “sendfeedback” is the address you want this feedback to go to. It is probably best for this to be a generic email address (eg support@xyz.com ) as opposed to a persons email.
This is also a good place to insert any Copyright notice or company logo.


        
        <item id="footer">
        

        <p/>
        

        Copyright XYZ 2007
        

        <p/>
        

        <span>
        

        Send
        

        <a>
        

        <includeAttribute name="href" item="MailToLink">
        

        <parameter>{0}</parameter>
        

        <parameter>{1}</parameter>
        

        </includeAttribute>
        

        comments
        

        </a>
        

        about this topic to XYZ Development Team
        

        </span>
        

        

        </item>
        

        <item id="MailToLink">javascript:sendfeedback('Documentation Feedback
        (Sandcastle CTP): ', '{1}', 'support@xyz.com');</item>