Recently I have been designing an Application Framework in .NET/ASP.NET 2.0.
It went well and I was thinking of generating the documentation using Visual Studio 2005 as I used to do in VS 2003. I could not find something like “Build Comment Web Pages” under Tools and I realized that that option has been removed in 2005.
MS talks of automating a lot of things and getting less and less work done for the developer and instead of improving that feature, it was totally removed.
I searched for some alternatives and the following came as options:
- Write Custom XSL sheets
- HelpStudio Lite from Innovasys that is shipped as a part of VS2005 SDK
- NDoc for Visual Studio 2005
I found some examples that shows writing XSLs for generating the HTML files, but I felt that will be kind of an over kill. . I was looking for a solution that can generate HTML/CHM help files directly from a Visual Studio 2005 Solution.
The second option, HelpStudio Lite, the basic functionality is free when you install the 2005 SDK, but since it is not integrated with the VS 2005 Projects, it is of not much useFor this functionality, you have to buy the product Document! X from Innovasys.
(http://www.innovasys.com/products/dx5/overview.asp). The single license version of this tool costs arnd $550.
So I decided to try NDoc and it turned out to be working well.
Here are the steps to get it working.
- Download the NDoc2005
Download the Beta Source code (as of now) from :
http://prdownloads.sourceforge.net/ndoc05/
Please make sure to download the Source Code and not the binaries. The binaries on running gave me an error:
Exception: System.IO.DirectoryNotFoundException
Could not find a part of the path 'D:\Documenter\Msdn\xslt\namespace.xslt'.
This is a known issue as a result of path hard coding.
So the solution is to download the source code.
- Compile the NDoc2005 Source Code
- Generate Documentation
Now DONOT try to run the NDoc Application by clicking F5. I did that initially and I had a solution that had around 5-6 projects. It was failing giving an error: Falied to load Assembly…blah..blah..
So the solution is to run the NDocGui.exe from NDoc2005\src\Gui\bin\Debug path.
Now before starting the generation, you need to enable the XML document generation for each project in VS 2005(Project Properties->Build->Output->XMlDocumentationFile)
Now add the decoration for you class and methods.
I found some good article on this at:
http://www.codeproject.com/csharp/csharpcommentinganddocs.asp
which could be a good starting point.
Now run the NDocGui.exe and specify ur solution name. It took a good amount of time to convert, but it is really fantastic.
You get the MSDN style documentation, very neat and clean.
Thanks a lot to NDoc..!!
So happy documentation to all..!!!
Update : 07-25-2006:
I made a wrong statement in my last post:
DONOT try to run the NDoc Application by clicking F5.
So the solution is to run the NDocGui.exe from NDoc2005\src\Gui\bin\Debug path
It is one and the same and I find, it was made bcose of some bad assumptions.
But afterwards, it was failing to generate the documentation giving an exception :
Falied to load Assembly
It was failing inside:
NDoc2005\src\Documenter\Msdn\MsdnHtmlUtilitiesV20.cs
for the method : InitializeNamespaces()
When I analyzed the code, I found that , it is failing to load the dependent assemblies of the assembly for which documentaion need to be generated. The reason is that the Assembly.LoadWithpartialName(name) will try to load the assembly from the AppDomain’s bin directory or from any of the configured path. This assembly is the one, whose path may be no way related to that of the NDocGui.exe.
So I decided to use the following logic:
- Load the dependent assembly from the CodeBase of the main assembly. This assunes that the dependent assemblies will be there under the bin of the main assembly
- But this logic will fail for the GAC assemblies like mscorlib, System.Data which are also dependent assemblies. So in the catch() block, I tried to load them with FullName.
And this worked and the documentation works like a charm now..!
Here is the full function I modified. The modified being in yellow color.
File : NDoc2005\src\Documenter\Msdn\MsdnHtmlUtilitiesV20.cs
for the method : InitializeNamespaces()
///
/// Initialize namespace dictionary
///
public static void InitializeNamespaces(Project project)
{
// If we don't have namespaces list yet, go through each referenced assembly,
// load the assembly, get the types, then cache the namespaces for all public types.
if (namespaces.Count == 0)
{
foreach (AssemblySlashDoc doc in project.AssemblySlashDocs)
{
//
string strDllFullPath = doc.Assembly.Path;
string strDllPath = strDllFullPath.Substring(0, strDllFullPath.LastIndexOf(@"\")+1);
//
Assembly theAssembly = Assembly.LoadFrom(doc.Assembly);
AssemblyName[] assemblies = theAssembly.GetReferencedAssemblies();
foreach (AssemblyName an in assemblies)
{
//Assembly assembly = Assembly.LoadWithPartialName(an.Name);
Assembly assembly = null;
try
{
assembly = Assembly.LoadFrom(strDllPath + an.Name + ".dll");
}
catch(Exception ex)
{
try
{
assembly = Assembly.Load(an.FullName);
}
catch (Exception ex1)
{
continue;
}
}
if (assembly == null)
{
throw new System.IO.FileNotFoundException(String.Concat("Unable to locate the referenced Assembly ", an.Name));
}
Type[] assemblyTypes = assembly.GetTypes();
foreach (Type type in assemblyTypes)
{
if (type.IsPublic)
{
namespaces[type.Namespace] = type.Namespace.Replace('.', '_') + '_';
namespaces[type.Namespace.Replace(".", "")] = type.Namespace.Replace('.', '_') + '_';
}
}
}
}
}
}
I am not sure whether this is the bext fix for the problem I faced with NDoc, but this makes it working..!!