Create MSDN-style class documentation CHM files for your assemblies
2006-08-13 12:03
344 查看
http://www.codeproject.com/useritems/SandcastleCreateBat.asp
Link label to open output directory. (5 Aug 2006)
Now supports wildcards (i.e. class documentation for multiple assemblies in the same CHM file). As you can see in the screenshot, just specify
Multiple assemblies supported
Simply re-run the BAT script when you need to recompile your documentation (no need to run a GUI and re-select assembly/comments files)
Doesn't overwrite help project if it exists (so you can modify it in Help workshop - especially handy for setting the default page so you don't get the ! icon when you open the CHM)
Option to keep or delete the working files after compiling your CHM
The configuration utility automatically fills the XML path and the CHM path when you select your assembly. (So long as the XML file exists and the CHM field is empty)
BAT script doesn't have any nice logging or friendly messages or error handling.
Click Create BAT, which will customise the BAT script and save it to the same folder that you selected for the CHM file (filename:
Note: You can move the
In
Two small excerpts from
As you can guess,
2) HTML Help 1.4 SDK
3) .NET framework 2.0
As you can see all the paths are configured. The tricky part while developing this was figuring out what customisation sandcastle.config required to be able to find it's assemblies and XML files and generate the HTML files to the correct directory. There was no documentation about this at the time, nor any documentation about the arguments.
Note: Sandcastle installation adds
Introduction
Sandcastle is Microsoft's new tool for generating MSDN-style documentation from your .NET assemblies and in-code XML comments. More info here^. On 29 July 2006 they released the CTP, and the blog soon followed up with an 11-step manual process to generate the CHM file using their test class. It seemed easy enough to create a BAT script to accomplish all this automatically, however there were a few issues that made this non-trivial. I've come up with a BAT script to automate this process, as well as a configuration utility.Updates
Link label to open output directory. (5 Aug 2006)
Now supports wildcards (i.e. class documentation for multiple assemblies in the same CHM file). As you can see in the screenshot, just specify
*.*as the assembly file, and
*.xmlas your comments file. The BAT script and sandcastle.config have been updated to support this, and it is working well for me. (2 Aug 2006)
Advantages
Multiple assemblies supported
Simply re-run the BAT script when you need to recompile your documentation (no need to run a GUI and re-select assembly/comments files)
Doesn't overwrite help project if it exists (so you can modify it in Help workshop - especially handy for setting the default page so you don't get the ! icon when you open the CHM)
Option to keep or delete the working files after compiling your CHM
The configuration utility automatically fills the XML path and the CHM path when you select your assembly. (So long as the XML file exists and the CHM field is empty)
Disadvantages
BAT script doesn't have any nice logging or friendly messages or error handling.
Configuration Utility
Browse for your .NET assembly. If an XML file with the same path exists, the XML path is automatically set. The CHM path is also automatically set using the same path, unless you specified a CHM path already. If you check the Delete working files checkbox, the "output" folder containing the HTML help project, HTML files, art files etc will deleted by the batch script.Click Create BAT, which will customise the BAT script and save it to the same folder that you selected for the CHM file (filename:
sc_compile.bat). And the customised
sandcastle.configfile will also be saved to this folder (with the correct paths as per the manual setting in
template.xml). Now just double click
sc_compile.batand wait for it to work it's magic. You should end up with the CHM file that you specified.
Note: You can move the
sc_compile.bat&
sandcastle.configto another folder if you want - the BAT script will run from anywhere. When it runs it creates an
outputfolder which is where all the working files are generated/copied to. If you checked the checkbox in the configuration utility then this folder is automatically deleted once the CHM compile is complete.
What's this template.xml?
Well, I'm not a big fan of XSLT for simple template transformations. And theString.Format()can be really confusing with various {0}..{n} scattered throughout the source string. A few years ago I created a class to perform replacements by processing replacement variables which correspond to element names.
In
template.xmlyou can edit two settings that are not editable using the configuration utility. They are:
SandCastleInstallPath&
HtmlHelpInstallPath. If you selected different install paths for Sandcastle or HTML Help you will need to change these values manually.
Two small excerpts from
template.xml:
<AssemblyPath>C:/test_sc/assembly here/ScrollingGrid.dll</AssemblyPath> <XmlCommentsPath>C:/test_sc/assembly here/ScrollingGrid.xml</XmlCommentsPath>
MRefBuilder "{$AssemblyPath$}" /out:reflection.org copy "{$XmlCommentsPath$}" comments.xml
As you can guess,
{$AssemblyPath$}gets replaced with the
AssemblyPathnode's text. The class to perform this replacement functionality is included in the source.
Requirements
1) Sandcastle2) HTML Help 1.4 SDK
3) .NET framework 2.0
BAT script
This is the latest edition of the BAT script:if not exist output mkdir output cd output if not exist comments mkdir comments del comments/*.xml copy "C:/Inetpub/wwwroot/_dev/ScrollingGrid/bin/asb/*.xml" comments MRefBuilder "C:/Inetpub/wwwroot/_dev/ScrollingGrid/bin/asb/*.*" /out:reflection.org XslTransform "C:/Program Files/Sandcastle/ProductionTransforms/AddOverloads.xsl" reflection.org | XslTransform "C:/Program Files/Sandcastle/ProductionTransforms/AddGuidFilenames.xsl" /out:reflection.xml XslTransform "C:/Program Files/Sandcastle/ProductionTransforms/ReflectionToManifest.xsl" reflection.xml /out:manifest.xml if not exist html mkdir html if not exist art mkdir art if not exist scripts mkdir scripts if not exist styles mkdir styles copy "C:/Program Files/Sandcastle/Presentation/art/*" art copy "C:/Program Files/Sandcastle/Presentation/scripts/*" scripts copy "C:/Program Files/Sandcastle/Presentation/styles/*" styles BuildAssembler /config:../sandcastle.config manifest.xml XslTransform "C:/Program Files/Sandcastle/ProductionTransforms/ReflectionToChmContents.xsl" reflection.xml /arg:html="html" /out:"Test.hhc" if not exist help_proj.hhp copy "C:/Program Files/Sandcastle/Presentation/Chm/test.hhp" help_proj.hhp "C:/Program Files/HTML Help Workshop/hhc.exe" "%CD%/help_proj.hhp" @copy "Test.chm" "../doc.chm" @cd .. REM @rd /s /q output @pause
As you can see all the paths are configured. The tricky part while developing this was figuring out what customisation sandcastle.config required to be able to find it's assemblies and XML files and generate the HTML files to the correct directory. There was no documentation about this at the time, nor any documentation about the arguments.
Note: Sandcastle installation adds
C:/Program Files/Sandcastle/ProductionToolsto the Windows
PATHenvironment variable. However if you have an issue running
MRefBuilder,
XslTransform, and
BuildAssembleryou can convert these calls to absolute paths (just update
template.xml).
Conclusion
I think Microsoft have done a good job on the interface of the generated HTML files (i.e. DHTML capabilities etc), which is the main thing that piqued my interest in this release. I haven't seen any good quality MSDN-style documentation from other documentation compilers - but I must admit I haven't experimented with the latest version of NDOC.相关文章推荐
- A duplicate insert block exists for class "COneValuDlg" in the source files
- class and type for classic and new-style class.
- Implementing your own base class for user controls in Silverlight 2
- HOWTO: Provide Your Own Window Class Name for an MFC Dialog Box
- Creating your own ODS Style Template for PDF Output
- Class Wizard Error: A duplicate insert block exists for class (CMyclass) in the source files
- Could not resolve all files for configuration ':classpath'.Could not find com.android.tools.
- ICE Manual(Documentation for Ice 3.5)---Slice Source Files
- 【原】java学习笔记 【二】 常见错误 Class files on classpath not found or not accessible for
- c++ how to make your own class a valid key type for std::map?
- Choose unique values for the 'webAppRootKey' context-param in your web.xml files!
- Enable VT-x in your BIOS security settings (refer to documentation for your computer)
- IntelliSense for your Custom QTP Class in 6 Steps
- 【DataStructure】A useful util class for reading and writing files
- 解决MFC对话框类不能建立成功的方法(出现unable to open the files XX for class XX)
- java web error:Choose unique values for the 'webAppRootKey' context-param in your web.xml files
- Using xcconfig files for your XCode Project
- Class for reading INI files
- Choose unique values for the 'webAppRootKey' context-param in your web.xml files 解决办法
- Could not resolve all files for configuration ':classpath'.Could not find com.android.tools.