Having problems with your account or logging in?
A lot of changes are happening in the community right now. Some may affect you. READ MORE HERE

Generate code documentation when building Visual COBOL Applications

Generate code documentation when building Visual COBOL Applications

Contents:

  1. Problem
  2. Sandcastle
  3. Steps for integration
  4. Remarks
  5. Known limitations for Visual COBOL
  6. Sandcastle.Targets file
  7. Watch Video Demo

Problem:

You want to generate automatically MSDN style help when building managed COBOL applications.

Sandcastle:

Sandcastle is a documentation compiler tool for managed Class Libraries. It produces accurateunderstandable, MSDN style documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments.

The tool can be downloaded and installed from http://sandcastle.codeplex.com/

Sandcastle includes a few components that need to be executed in order to generate the help file:

  • MrefBuilder.exe – Parses managed assemblies and generates XML output file with reflection information.
  • XslTransform.exe – Applies XSL transformations to an XML file.
  • BuildAssembler.exe – Creates HTML topics with generated syntax from the XML input.
  • ChmBuilder.exe – Generates an hpp file from the collected information which is needed by the hhc.exe (the HTLM Help compiler tool that is not included in the Sandcastle setup).

Steps for integration:

1.      Download Sandcastle from http://sandcastle.codeplex.com/releases/view/47665 and install it. In our case Sandcastle is installed in the default location - C:\Program Files\Sandcastle.

2.      Open your Visual COBOL project, go to the COBOL property page and select the “XML documentation file” option. With this option enabled, an output XML file with XML comments will be generated in the specified directory after building the project. Sandcastle extracts the XML comments from this file and hooks them to the corresponding types and members found in an assembly.

3.      Create a subfolder called ‘Docs’ in your projects folder. This will be the output folder for the generated documentation.

4.      Copy the sandcastle.config file from \Sandcastle\Presentation\vs2005\configuration folder to the Docs folder created earlier. We need to do this in order to modify the copy of the configuration file (not the original), so that it works for our application.

5.      Open the sandcastle.config file in a text editor and search for “.\comments.xml” in order to make a small modification there. This modification will point Sandcastle to the XML output file generated from our application. You need to replace “.\comments.xml” with the path to the XML file from our application – “..\bin\Debug\SandcastleDemo.xml” or “..\bin\Debug\*.xml”.

6.      Create Sandcastle.Targets file from the XML code posted at the end of this article into your projects folder. This file contains an additional msbuild target called “GenerateCodeDocumentation”. This target calls the executable components from Sandcastle in sequence with the appropriate arguments. The targets file assumes you have Sandcastle installed in the default “Program Files” folder and that you have created a Docs subfolder on project level with a sandcastle.config file in it. With different paths, you need to edit the Sandcastle.Targets file to point to your specific location.

Import the Sandcastle.targets file into the Visual COBOL project file and add a call to the GenerateCodeDocumentation target. To do this open the .cblproj file in a text editor or unload it and edit it in Visual Studio.

Add <Import Project=".\Sandcastle.Targets" /> which will import the targets file into the Visual COBOL build file and add a call to the target defined in the targets file:

<Target Name="AfterBuild">

    <CallTarget Targets="GenerateCodeDocumentation">

    </CallTarget>

</Target>

7.      Save the project file, reload and build the project.

8.      After the build has finished you should be able to find the generated help file in the “Docs\Output\chm” subfolder of your project.

Remarks:

Keep in mind that this article illustrates the main points of configuring help generation for particular application that consists of only one project. In real life scenarios, we would work with multi-project applications which need to be configured differently. It is worth mentioning that help generation is time consuming job and can take significant part of the build time.

Known limitations for Visual COBOL:

Sandcastle does not display XML documentation for constructors and properties because the generated XML entries for these types differ from the ones the other .NET languages have.

Sandcastle.Targets file:

Note: Sandcastle.Targets is a modified version of the Help.Targets file which can be found at http://code.msdn.microsoft.com/sandcastleutil/Release/ProjectReleases.aspx?ReleaseId=5044 and is distributed under the MICROSOFT PUBLIC LICENSE (Ms-PL):  http://code.msdn.microsoft.com/sandcastleutil/Project/License.aspx.

Using a text editor, create a Sandcastle.Targets file and paste in it the code below:

 

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="GenerateCodeDocumentation">
<!--chm/hxs compiliers are installed under '$(ProgramFiles) (x86)' folder on 64-bit machine. -->
<Choose>
<When Condition="Exists('$(ProgramFiles) (x86)')">
<PropertyGroup>
<BuildTools>$(ProgramFiles(x86))</BuildTools>
</PropertyGroup>
</When>
<Otherwise>
<PropertyGroup>
<BuildTools>$(ProgramFiles)</BuildTools>
</PropertyGroup>
</Otherwise>
</Choose>

<PropertyGroup>
<!-- Setup some paths to directories -->
<BinDir>$(OutputPath)</BinDir>
<!-- This is the path to the sandcastle config file that should be used for the generation of the docs.
A default one exists in the installation folder of Sancastle.
This is also the output folder for the documentation -->
<DocDir>.\Docs</DocDir>
<SandCastleDir>$(BuildTools)\SandCastle</SandCastleDir>
<DocHtmlDir>$(DocDir)\Output\html</DocHtmlDir>
<DocChmDir>$(DocDir)\Output\chm</DocChmDir>
<DocChmFile>SandcastleDemo</DocChmFile>
<SandCastleConfig>$(DocDir)\SandCastle.config</SandCastleConfig>

<!-- Executables -->
<SandCastleMrefBuilderExe>"$(SandCastleDir)\ProductionTools\MrefBuilder.exe"</SandCastleMrefBuilderExe>
<SandCastleBuildAssemblerExe>"$(SandCastleDir)\ProductionTools\BuildAssembler.exe"</SandCastleBuildAssemblerExe>
<SandCastleXslTransformExe>"$(SandCastleDir)\ProductionTools\XslTransform.exe"</SandCastleXslTransformExe>
<SandCastleChmBuilderExe>"$(SandCastleDir)\ProductionTools\ChmBuilder.Exe"</SandCastleChmBuilderExe>
<HhcExe>"$(BuildTools)\HTML Help Workshop\hhc.exe"</HhcExe>

<!-- XSL Stuff-->
<SandCastleApplyVSDocModelXsl>"$(SandCastleDir)\ProductionTransForms\ApplyVSDocModel.xsl"</SandCastleApplyVSDocModelXsl>
<SandCastleAddFriendlyFileNamesXsl>"$(SandCastleDir)\ProductionTransForms\AddFriendlyFilenames.xsl"</SandCastleAddFriendlyFileNamesXsl>
<SandCastleReflectionToManifestXsl>"$(SandCastleDir)\ProductionTransForms\ReflectionToManifest.xsl"</SandCastleReflectionToManifestXsl>
<SandCastleCreateVSTocXsl>"$(SandCastleDir)\ProductionTransForms\CreateVSToc.xsl"</SandCastleCreateVSTocXsl>

</PropertyGroup>

<ItemGroup>
<SandCastleScripts Include="$(SandCastleDir)\Presentation\VS2005\Scripts\**\*.*" />
<SandCastleStyles Include="$(SandCastleDir)\Presentation\VS2005\Styles\**\*.*" />
<SandCastleIcons Include="$(SandCastleDir)\Presentation\VS2005\Icons\**\*.*" />
</ItemGroup>

<Target Name="GenerateCodeDocumentation">
<Message Text="Generating Code Documentation" />
<!-- Ensure SandCastle.Config exists in docs directory, MrefBuilder tool will fail if it doesn't -->
<!-- Create HTML Directory under doc-->
<MakeDir Directories="$(DocHtmlDir)" Condition="!Exists($(DocHtmlDir))" />

<!-- Create the Chm Directory -->
<MakeDir Directories="$(DocChmDir)" Condition="!Exists($(DocChmDir))" />

<!-- Copy everything from Scripts, Icons, Styles Directories from {SandCastleRoot}\Presentation\VS2005 to CHM directory-->
<Copy SourceFiles="@(SandCastleScripts)" DestinationFolder="$(DocChmDir)\Scripts\%(RecursiveDir)" Condition="!Exists('$(DocChmDir)\Scripts')" />
<Copy SourceFiles="@(SandCastleStyles)" DestinationFolder="$(DocChmDir)\Styles\%(RecursiveDir)" Condition="!Exists('$(DocChmDir)\Styles')" />
<Copy SourceFiles="@(SandCastleIcons)" DestinationFolder="$(DocChmDir)\Icons\%(RecursiveDir)" Condition="!Exists('$(DocChmDir)\Icons')" />

<!-- Run MrefBuilder (Introspection on assemblies) to create a basic reflection xml -->
<Exec Command="$(SandCastleMrefBuilderExe) ..\$(BinDir)\*.dll /out:mref.xml" WorkingDirectory="$(DocDir)"/>

<!-- run xsltransform with ApplyVSDocModel.xsl file on original reflection xml output by mref builder tool -->
<Exec Command="$(SandCastleXslTransformExe) mref.xml /xsl:$(SandCastleApplyVSDocModelXsl) /out:afterapplyvsdocmodelxsl.xml" WorkingDirectory="$(DocDir)" />

<!-- Generate friendly file names for HTML documents-->
<Exec Command="$(SandCastleXslTransformExe) afterapplyvsdocmodelxsl.xml /xsl:$(SandCastleAddFriendlyFileNamesXsl) /out:reflection.xml" WorkingDirectory="$(DocDir)" />

<!-- Generate Manifest (List of Topics)-->
<Exec Command="$(SandCastleXslTransformExe) reflection.xml /xsl:$(SandCastleReflectionToManifestXsl) /out:Manifest.xml" WorkingDirectory="$(DocDir)" />

<!-- Create Html Topic file by Running BuildAssembler tool -->
<Exec Command="$(SandCastleBuildAssemblerExe) manifest.xml /config:..\$(SandCastleConfig)" WorkingDirectory="$(DocDir)" />

<!-- Generate an Intermediate TOC file -->
<Exec Command="$(SandCastleXslTransformExe) reflection.xml /xsl:$(SandCastleCreateVSTocXsl) /out:toc.xml" WorkingDirectory="$(DocDir)" />

<!-- Generate HHP File-->
<Exec Command="$(SandCastleChmBuilderExe) /project:$(DocChmFile) /html:Output\html /lcid:1033 /toc:toc.xml /out:Output\Chm" WorkingDirectory="$(DocDir)" />

<!-- Generate CHM File -->
<Exec Command="$(HhcExe) ..\$(DocChmDir)\$(DocChmFile).hhp" WorkingDirectory="$(DocDir)" ContinueOnError="true"/>

</Target>
</Project>

Watch Video Demo:

http://screencast.com/t/DGZZNz7Jd

DISCLAIMER:

Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Version history
Revision #:
1 of 1
Last update:
‎2012-06-21 16:58
Updated by:
 
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.