Generate documentation under .Net 2.0?

Question

I really need to generate some documentation under .Net 2.0. I know that this issue has been raised in a previous post few month ago, but no explicit solution has been provided. Also the NDoc project seems dead (as suggest the broken wiki).

Does anyone has a practical (even minimal) solution to generate documentation for .Net 2.0 ?

Thanks in advance,
Joannes

Answer 1

Hi Joannes,

There is an option to create an XML file based on the comments entered. You probably can generate that and apply an XSL to that to get an HTML appearance to the XML.

Regards,
Vikram

Answer 2

Actually, I just did patch NDoc in order to skip any generic type. For an example of what I did get, look at the NSvm documentation.

 Although, it does not seem too complicated to handle generic types (it's not that different from classical types). I hope that the NDoc team will do it soon.

Joannes

Answer 3

NDoc is in fact being updated and will fully support 2.0 including generics, but progress is slow due to real life issues on the part of the maintainer. I tested a few betas which already worked quite well but it's been a month since I've heard anything. When the RTM is out I'm going to mail him and ask what's happening.

Answer 4

Any update on progress of Ndoc towards support of v2.0 of .Net since the last posts above? I noticed the wiki appears locked or something so not sure if this is indicative of a a hiatus or not. No v2.0 version just a dead wiki link to some notes on how to do it using the code...

This tool was such a useful addendum to v1.0 and v1.1 and have used it on all projects since early 2002. Seems a pity it will not be there for v2.0 and its absence leaves a big *** in C#/.Net auto documenting. As im currently working on a large SOA solution, possibly in 2.0, im interested in getting some top quality doco out for consumers.

Has MS ever thought of bringing it (or a version of it) inhouse as with nunit? Would be very useful addition to the suite I thought....

Cheers
Ross Nelson

Answer 5

Well, I just mailed the maintainer and will keep you posted on anything I hear.

By the way, MS didn't actually adopt NUnit as far as I know -- both with NUnit and NAnt (= MSBuild) they did look at these products but eventually rolled their own without reusing the source code. I gather it's a licensing issue... they don't want any part of Visual Studio connected to an open source license.

But I agree that it would be nice if they eventually cloned NDoc in the same way. It's pretty silly that MS no longer provides any way to produce documentation from XML comments.

Answer 6

Thanks chris,
was also talking to Tom Hollander who works in patterns and practices who I worked with on an early .Net project in Australia back in 2002. He's in redmond now and pointed me at the following which sort of explains all:

http://sourceforge.net/mailarchive/forum.php?thread_id=8415964&forum_id=38707

Cheers
Ross

Answer 7

Thanks for the link, I wasn't aware that Kevin had started posted to the SourceForge mailing list again!  Our beta mailing list was completely dead since early September.

Looks like he's already busy finishing up the project but doesn't have the RC/RTM so we'll probably have to wait until some time after VS2005 is publically available before NDoc 2.0 gets released.

Answer 8

Lets hope the ndoc team (read kevin) can get it up and working with 2005 in the short term. As a solutions architect I think that ndoc is indispensible for producting technical documentation across any layer in your development space, either interfaces or internal implementation. MS really needs to think about making it a standard add-on going forward, by whatever arrangement.

Answer 9

By the way, just in case you or other NDoc users were not aware of it, there is another way to create formatted HTML pages from XML comments: http://www.doc-o-matic.com/

Doc-o-matic is much more powerful than NDoc -- for example, it supports non-.NET languages and has a built-in editor and spell checker for the comment text -- but it costs a fair chunk ($500 for .NET). Might be worth it if you need nicely formatted .NET 2.0 documentation right now, or if you can use the extra features.

PS: Speaking of money, in the SF thread linked above Kevin complains about a lack of donations to the NDoc project... so if you like NDoc and want to encourage him to work faster, you should probably send a few bucks his way!

Answer 10

For 2.0, I am using Doxygen. http://www.stack.nl/~dimitri/doxygen/

It generates html files from a subset of xml docs, will generate a chi help file if you want, pdf, rtf and latex documentation.  Correctly configured, it will generate a uml class diagarm, a call graph for your methods, and inheritance hierarchies.

The program is open source and is used extensively in the linux community. It also correctly parses generics. It has some cool features such as automatically generating links from your comments by simply writing out the class name.

What it doesn't do is parse your assemblies, or link to sdk documentation. References are strictly limited to the list of source files you feed it.

I find Doxygen more than satisfactory for a stop-gap measure until NDoc is gold or MS releases something useful.

Answer 11

It looks like a nice fellow has picked up NDoc and gotten it at least partially working on .NET 2.0 with Visual Studio 2005.
http://jonas.lagerblad.com/blog/?p=4
also
http://www.vehemence.org.uk/files/ndoc/ndoc-bin-1.3.1-v13.zip

Answer 12

I found this article (Japanese only)
http://blogs.wankuma.com/yaneurao/archive/2006/02/23/21472.aspx

and he said, just create NDocGui.exe.config file inside bin folder where NDocGui.exe is located.

<?xml version="1.0" ?> 
<configuration>
<startup>
       <supportedRuntime version="v2.0.50727" />
       <supportedRuntime version="v1.1.4322" />
       <requiredRuntime version="v1.1.4322" />
</startup>
</configuration>


Note:Make sure your project is generating xml file and installing HTML Help Workshop
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

Answer 13

Joannes,

Thanks for you post. As I mentioned in the other thread our plans are to release documentation compilers for .Net 2.0 as a Community Technology Previews (CTP) version by the end of June 2006 and then RTM by the end of August 2006. I will have a detailed post about this before our CTP release next month. Cheers.

Anand..

Microsoft Corporation

Answer 14

Hi All,

If you haven't already seen this, here is the hyperlink to the latest NDoc05 Beta on sourceforge:

http://sourceforge.net/project/showfiles.php?group_id=163095

Hope this helps,

Kind regards,

Frank M. Palinkas
MCP, MCT, MCSE, MCDBA, A+
Microsoft Registered Partner
Senior Technical Communicator & Web Accessibility Designer

Answer 15

It is great news that Microsoft is addressing this need.  I don't know what other thread you are referring to where these plans were discussed.  Can you tell me where I should be watching to learn when the CTP is available?

FYI, my specific need is for ASP.NET documentation when using Visual Basic 2005 as the language.  I hope the plans will cover that situation.  Right now, it doesn't appear there is even a way to generate a file containing all my XML comments that I could do in VS 2003.  So the project I'm working on, which was upgraded from VS 2003, can no longer update it's documentation.

Thanks in advance.

 

 

Answer 16

BradNet wrote:

my specific need is for ASP.NET documentation when using Visual Basic 2005 as the language

You can use our VBdocman .NET for your needs.It will also support C# and new MSDN2 look in a two or three weeks.

Answer 17

I was happy to hear about this. Is there any more news about the documentation compilers at this stage?

Answer 18

Anand,

Where can we expect any announcements to be made regarding the June CTP with the new Help Compilers?

Regards,

Paul M. Seabury

Answer 19

Hi there

I downloaded NDoc05 beta and when I try to create doco of a DLL I have written I get the error below. Seems to be looking for a path, "C:\Documenter\Msdn\xslt\namespace.xslt" that I don't have. I tried looking for some option to set the correct path, but couldn't find one.

Anyone know whats happening?

Thanks
Dave


Error compiling the namespace stylesheet



Exception: NDoc.Core.DocumenterException

Error compiling the namespace stylesheet



Exception: System.Exception

Error compiling the namespace stylesheet



Exception: System.IO.DirectoryNotFoundException

Could not find a part of the path 'C:\Documenter\Msdn\xslt\namespace.xslt'.





Exception: NDoc.Core.DocumenterException
   at NDoc.Documenter.Msdn.MsdnDocumenter.Build(Project _project) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\MsdnDocumenter.cs:line 565

   at NDoc.Gui.BuildWorker.ThreadProc() in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Gui\BuildWorker.cs:line 88

Exception: System.Exception
   at NDoc.Documenter.Msdn.StyleSheetCollection.MakeTransform(String name, XsltResourceResolver resolver) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\StyleSheetCollection.cs:line 115

   at NDoc.Documenter.Msdn.StyleSheetCollection.AddFrom(String name, XsltResourceResolver resolver) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\StyleSheetCollection.cs:line 96

   at NDoc.Documenter.Msdn.StyleSheetCollection.LoadStyleSheets(String extensibilityStylesheet) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\StyleSheetCollection.cs:line 58

   at NDoc.Documenter.Msdn.MsdnDocumenter.Build(Project _project) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\MsdnDocumenter.cs:line 400

Exception: System.IO.DirectoryNotFoundException
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)

   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy)

   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize)

   at System.Xml.XmlDownloadManager.GetStream(Uri uri, ICredentials credentials)

   at System.Xml.XmlUrlResolver.GetEntity(Uri absoluteUri, String role, Type ofObjectToReturn)

   at NDoc.Core.XsltResourceResolver.GetEntity(Uri absoluteUri, String role, Type ofObjectToReturn) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Core\XsltResourceResolver.cs:line 138

   at NDoc.Documenter.Msdn.StyleSheetCollection.MakeTransform(String name, XsltResourceResolver resolver) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\StyleSheetCollection.cs:line 105

Answer 20

Hi
Has Microsoft released documentation compilers for .Net 2.0 ? and where I can download this version
Thks

Answer 21

Tomorrow is the end of June. Is this released?

Answer 22

Paul and everyone,

Sorry about the slow response. We did a code complete of "Sandcastle" CTP on June 15th and currently we are testing the tool building our .NetFramework documentation. We would like to release the CTP in Microsoft download center by next week. The perf in our testing has been great as we are able to build the entire framework content in less than 1 hour. I am in the process of going through final check and code signing required to post this in our download center.

Please expect the CTP in the next week or so and I will provide an update here as soon I post the CTP. 

Anand..

 

Answer 23

Hi,

I get the same error message where the application is looking for the file: "namespace.xslt"

The interesting part is that the application looks for it in an entirely different directory, almost 3 levels above the application directory.

Take a look at this-

The NDoc version in question is installed at: F:\rajat\downloads\Ndoc\nDoc2005beta\NDoc2005BetaGui

whereas the error message shows that the application is looking for it in the directory: F:\Rajat\downloads\Documenter\Msdn\xslt\namespace.xslt

I tried searching for the file but didnot find it anywhere.

 

Does any one have any comments/suggestions/reslutions on this ???

 

Rajat

Answer 24

Hi,

Found a workaround on:

http://sourceforge.net/tracker/index.php?func=detail&aid=1479548&group_id=163095&atid=826379

It suggests downloading the source and building it again.

 

Seems to work for now   

 

Rajat

Answer 25

I see that this thread is prominently featured in the "Can't find the answer?" sidebar so I'll add my announcement here as well:

The current unofficial alpha version of NDoc 2.0 is now available for download at http://www.kynosarges.de/NDoc.html -- please read the page for more information.

Answer 26

I had some success with this after converting the NDoc project to 2.0 (just the Solution & Project files, not the cs files) and building it with VS 2005.

The source I used can be found here: http://ndoc.sourceforge.net/ndoc-nightly.zip

The help docs for my C# 2.0 DLL build fine, although generics don't show correctly.

Answer 27

Have you tried using the NDoc 2.0 alpha build linked above?  It should work just fine...

Answer 28

funny, it works!

 

 

Answer 29

Can anyone send a link where are those microsoft`s help compilers that shoud have been available in July 2006.

Answer 30

I tried that and it started generating HTML documentation right, but then broke:

NDoc Documenter Error

Exception: NDoc.Core.DocumenterException

Unable to find the HTML Help Compiler. Please verify that the HTML Help Workshop has been installed.

Exception: NDoc.Core.DocumenterException

Unable to find the HTML Help Compiler. Please verify that the HTML Help Workshop has been installed.

 

It is November now, is there anything that can create HTML documentation in MSDN style and to work right?????

If there is please send the link.

Answer 31

Sandcastle was updated for the september CTP (http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en), and you can find a couple of community built GUI's @ http://www.sandcastledocs.com/Wiki%20Pages/Sandcastle%20GUIs%20from%20Community.aspx that should get you up to speed quickly.

Cathal

Answer 32

This works !!

Answer 33

Chris Nahr wrote:

I see that this thread is prominently featured in the "Can't find the answer?" sidebar so I'll add my announcement here as well: The current unofficial alpha version of NDoc 2.0 is now available for download at http://www.kynosarges.de/NDoc.html -- please read the page for more information.

I downloaded this version and it works fine.  Use the 'MSDN-CHM' option.  The output chm documentation for this 2.0a version definitely looks a lot closer to the actual MSDN documentation compared to NDoc 1.3.1

Answer 34

Wow dude - you saved my life!!

I have this project been working on for years! with like 4 business objects with tons of variables, methods, enumerables etc. we just added on another programmer to our group and I have to document all these methods and classes - luckily I put comments on most of them.

Using visual studio 2005, you would think that by now Microsoft would have some tool to create help files ('duh'), NDOC rules men! I made those changes and it generated all the documentation and then some - thanks for the config code snippet!

Answer 35

here's a link to nDoc for .NET 2.0

Source and binaries are both avaliable. This version handles generics (only for C# at the moment).

http://jonas.lagerblad.com/blog/?p=4

I could not get the binaries to work, so i just compiled the source code (VS2005 professional) and it works well.

 

Nitin Mistry

 

 

Answer 36

Incredible! What a quick and easy solution to a problem which seemed very problematic! Hats off to you Kiichi Takeuchi!