locked
Insert custom images into documentation (e.g. classdiagrams)

    General discussion

  • A lot of Sandcastle users that use the SandcastleGUI tool have asked me questions how to insert custom images into the documentation output. Basically what people were trying to accomplish is documentation output that holds uml-classdiagrams visualizing their classes/ interfaces/ method and so on.

     

    On the following url their is a nice example of this feature:

    http://www.inchl.nl/help/e08e8df3-c5d1-19f6-4b32-5c2b97cad4cc.htm

     

    For now I will explain how this kind of output was achieved using SandcastleGUI, but I hope that Eric and Dave will also put in extra comments how to achieve that using their tools (or how to achieve this using Sandcastle straight on from the command line).

     

    Step1: create your images manually and store them into a separate directory (flat hierarchy: no subdirectories allowed)
    Step2: specify xml comments in your source code referring the image (by filename, do not use path/directory names)
     
    something like:
     
    /// <summary>
    /// This class does something.
    /// <remarks>
    /// There is a class diagram.<br/>
    /// <img src="myClassImage.png" />
    /// </remarks>
    /// </summary>
    public class MyClass
    {
    .....
    }
     
    Step3: Configure SandcastleGUI and specify the 'directory to include in documentation (optional)' pointing the
    directory that hold the images.
    Step4: Execute the documentation progress.
     
    SandcastleGUI will add the content of the image directory you specified to the documentation output. This way
    you can achieve custom images into a documentation output. Also you can use this technique for other things like embedding .zip files holding code examples etc...
     
    Some more information can be found at:
     
    About XML comments:
    http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
     
    About Sandcastle:
    http://www.sandcastledocs.com
     

    Stephan

    Friday, November 02, 2007 10:40 AM

All replies

  • Hi Stephan,

     

    I believe you mentioned before that a path such as ../art/ isn't required in the src attribute either when using your software, as in your example, which I think is a nice feature.

     

    Your example is pretty much how it can be done on the command-line as well, although a subdirectory such as ../art/ is usually necessary.  Though when compiling Help 1.x (and possibly Help 2.x as well, but I'm not sure), the compiler will automatically include images in the output when they are found in the src attribute of <img> tags, even if the .hhp file doesn't explicitly reference them.  For example, the [FILES] section in the HTML Help Workshop project file (.hhp) that is generated by Sandcastle (using a transformation or the ChmBuilder) includes art\*.gif, however if you reference a JPEG in the art directory, such as <img src="../art/classdiag.jpg"/> it will be included automatically without having to modify the .hhp file.

     

    Just something that I feel should be mentioned since it's not an obvious feature of Help 1.x given that Sandcastle hard-codes art\*.gif.

     

    - Dave

     

    Friday, November 02, 2007 11:09 AM
  • hi,

     

    Thanks for the comment Dave.

    You are right about the ../art/ part (I totally forgot about that Sad ). Having to put ../art/ as a prefix is very annoying.

    Although everyone uses Sandcastle, having to do so binds us to Sandcastle specifc xml-comments (this is not the way to go).

     

    Indeed all referenced files are included in the Help compilation, but this does not work for files that were indirectly referenced. This I will explain more:

     

    If you reference an html file that also references an other html file, both files are included in the output.

    However, if case you want to embed a package that contains two exotic files into the documentation, you possible only reference only one of them from within the xml-comments. This will result in a incomplete package. Its 100% logical why this occurs because the help compilation only knows how to interper html-based referenced files (it doesn't know that the first file actually comes with the second one as a single package). SandcastleGUI therefore adds each file that is located in the 'image' directory as a seperate include-item in the help compilation configuration, making sure all 'packages' are working and no files are excluded because they are 'not' referenced.

     

    Stephan

    Friday, November 02, 2007 11:43 AM
  • Hi Stephan,

     

    Indeed all referenced files are included in the Help compilation, but this does not work for files that were indirectly referenced. This I will explain more:

    That's a good point.  If you reference a file in script it won't be picked up by the compiler.

     

    SandcastleGUI therefore adds each file that is located in the 'image' directory as a seperate include-item in the help compilation configuration

    Does your software use ChmBuilder?   It uses a template in its configuration file to generate the .HHP, along with other settings, so it may be easier to manage than a custom .HHP template; although, ChmBuilder doesn't support a /config argument yet, which makes that particular feature difficult to use in an automation tool Sad

     

    (Beware though if you haven't used it yet; the .HHC output is different than the output from Sandcastle's XSL transformation - UL tags are now used to encapsulate a node and its children.)

     

    - Dave

    Friday, November 02, 2007 12:03 PM
  • SandcastleGUI uses ChmBuilder and creates a custom hhp file that hold all required settings Smile

     

    About the UL-tags.... since the October CTP I had a problem with incorrect toc.xml files (ChmBuilder crashed).

    Is it true that this 'feature' was introduced in this October release? In that case you are my hero, because SandcastleGUI adjusts the toc.xml file before kicking off the ChmBuilder progress; I went nuts on how that file was organized. SandcastleGUI also uses the toc.xml file to generate the table of contents html file for the website output. It also uses that file for generating the word-dictionary enabling a search features for websites.

     

    Stephan

     

    Friday, November 02, 2007 1:42 PM
  • Hi Stephan,

     

    About the UL-tags.... since the October CTP I had a problem with incorrect toc.xml files (ChmBuilder crashed).

    Is it true that this 'feature' was introduced in this October release?

    I'm not sure since I just started using ChmBuilder for DocProject in 1.9.0 RC, but I haven't had it crash yet.  I noticed after building a DocSite that the TOC only had one node and I then realized that the .HHC format was different, which was surprising Smile  I don't know how that relates to the toc.xml file though.  I guess if your toc.xml was valid when ChmBuilder crashed then you found a bug.

     

    See this discussion for an example of how the old format relates to the new format (I haven't done enough testing to guarantee that this is the only change, but it does work fine in DocProject now using, what I think, is the correct format):

     

    https://www.codeplex.com/Thread/View.aspx?ProjectName=DocProject&ThreadId=17226

     

    - Dave

    Friday, November 02, 2007 2:30 PM
  • This is covered in the Sandcastle Help File Builder's FAQ help file topic:

     

    How can I embed an image in a namespace, type, or member's help topic?

     

    Embedding an image in an element's help topic is a two step process. First, you must add the image to the help file builder project's AdditionalContent property. The second step is to edit the member's XML comments (summary, remarks, etc) to add the img tag. To embed an image in the Project Summary or Namespace comments, add the image tag to the help file builder's Project Summary notes or namespace comments. Below are two examples of embedding an image in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the image file. The first example assumes that the image is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the image is copied to an .\Images folder. In that case, you must also specify the folder name. As noted above, the image tag must be self-closing to conform to the XML specification.

     

    Example <img> Tag Usage

     

    /// <summary>
    /// A class member.
    /// </summary>
    /// <remarks>An image: <img src="../Process.gif"/>
    /// </remarks>
    public void TestMethod()
    {
        // ... Method implementation ...
    }

     

    /// <summary>
    /// A useful class.
    /// <p/>UML Diagram: <img src="../Images/TestClassUML.gif" alt="UML Diagram" />
    /// </summary>
    public TestClass
    {
        // ... Class implementation ...
    }

     

    Also note that there is the DrawBridge build component (www.castleapps.com) that auto generates class documentation.  I haven't seen an update on it for the past couple of CTPs so I don't know if it's still being actively developed and supported.

     

    Eric

     

    Friday, November 02, 2007 3:25 PM
  • I forgot to mention DocProject's support for images... oops

     

    To add images in XML code comments so that they work with DocProject, you can use any format that is relative from your project's Help\Html and Help\Html2 folders, but using ../Art/{image.ext} is recommended (the reason is below).  Then just import the image into your project in Visual Studio.

     

    Eric's explanation of the comments is thorough so here's just one more simple example showing how to float an image to the right side of the document so that the summary wraps around the image:

     

    Example HTML <img> tag in XML code comments

    /// <summary>

    ///   <img style="float:right;" src="../Art/design.jpg"/>

    ///   This text is probably not long enough to wrap,

    ///   but you get the idea!

    /// </summary>

    public class TestClass2 { }

     

    Note how the image tag is defined before the text.

     

    DocProject also provides a WYSIWYG (what you see is what you get) XML documentation editor.  The editor allows you to create external XML documentation (just like XML code comments, but not actually in your code files).  For more information, see How To Use The API Topic Management Dialog and search my blog for API Topic Management.

     

    To add an image in design mode, simply drag/drop it into the editor from an external source, such as a web browser, or right-mouse click and select Insert > Picture.  You can also add <img> tags manually in source mode.

     

    DocProject automatically imports images that you add in the editor into the local project's Help\Art folder when you save your changes.  It will automatically download images from a remote website or copy them from your local machine - from wherever the original location is.  It also automatically rebases the HTML (actually XML) so that the src attribute in all of your image tags point to the correct place.  For example, <img src="../art/myimage.jpg"/>.

     

    The next time you view your image in the XML documentation editor it is rebased again to the full path so that it is displayed correctly, so don't be confused when you see a full path in source mode.  When you save changes it rebases all image tags again to the virtual path, if necessary (only if the documentation was actually modified though).

     

    - Dave

    Friday, November 02, 2007 4:02 PM
  • Thank you Dave and Eric for your comments!

     

    Stephan

     

    Friday, November 02, 2007 4:08 PM