Author Topic: Using Both EA and NDoc documentation in .NET  (Read 4356 times)

MikeGale

  • EA Novice
  • *
  • Posts: 9
  • Karma: +0/-0
    • View Profile
Using Both EA and NDoc documentation in .NET
« on: November 02, 2003, 11:57:47 am »
I'm closing out an evaluation of EA.

Currently I'm considering using both EA and NDoc (like the MS documentation in CHM format).

It seems logical to interlink the two systems.

Does anyone have ideas and practical experience to share?

mcavigelli

  • EA Novice
  • *
  • Posts: 10
  • Karma: +0/-0
    • View Profile
Re: Using Both EA and NDoc documentation in .NET
« Reply #1 on: December 15, 2003, 08:06:40 am »
I export the class diagrams into a 'png' file. The html generated from NDoc references that file. When compiling the html to chm, the images are inlcuded into the chm file. Not too elegant I know, however...

The details:
1. Save the diagrams as images into a subfolder 'images' of your NDoc's html files. (I think Ndoc sometimes deletes all files in a directory, no subdirectories though). Filenames could follow a scheme like NS1.NS2.NS3.png

2. In the source code, I add per namespace a class with name NamespaceDoc, which is used from NDoc to document a namespace;-)

3. The compiler exports xml, even when it doesn't know the tags. So I add an 'img' tag in the documentation of the class.

namespace  NS1.NS2.NS3{
 /// <summary>Description of this namespace
 /// <img src="images/NS1.NS2.NS3.png" /></summary>
 public class NamespaceDoc{
 }
}

4. Recompile the solution

5.1 In the NDoc Project (Documentation Type: MSDN), set the OutputTarget property to 'HtmlHelpAndWeb'

5.2  set the 'UseNameSpaceDocSummaries' to true.

6. Build the NDoc project and you should be able to see the images in both the html pages and the chm file.

If you know of any more elegant way, let me know.

Matthias


MikeGale

  • EA Novice
  • *
  • Posts: 9
  • Karma: +0/-0
    • View Profile
Re: Using Both EA and NDoc documentation in .NET
« Reply #2 on: December 15, 2003, 12:10:53 pm »
Thanks Matthias,

In my tests I discovered that I could use (xmlified) img tags.  Your extra tips are most useful.

I did decide to use EA in my projects.

I'm currently using three forms of documentation.  In time I would like to merge these into one.

1)  Pure NDoc documentation.

2)  My own documentation which is produced as compiled help (CHM) files.  This is dead easy to do.  (I use Homesite to create content and the HTML Help Workshop to turn that into a CHM.)

3)  HTML format EA documentation.

This will head toward deeper integration but works as is.  Integration is likely to follow a track like:

A)  Check the ability to import other CHM's into a new build within Help Workshop.  That gives me a way to integrate the automatically created content into the manually controlled CHM.

B)  Build a CHM from EA HTML content.  The structure is a very regular with subdirectories etc.  I envisage a mixed automatic / manual approach initially.  In this a tool creates the basic HTML Help files by recursing the subdirectories and building the file list and navigation structure.  I haven't yet investigated putting names into the "site map" file.  I'd like to automate but expect to do it manually at first.

C)  Merge all three into one CHM.

The material won't initially be interlinked, but that may come later...

This is a fill in project and has no time line.