axaptapedia: Sandcastle

[Blog bot]

Источник: http://www.axaptapedia.com/Sandcastle
==============

Summary: /* Assembly information */

== Introduction ==

[http://sandcastle.codeplex.com Sandcastle] documentation compilers enable managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel. With Dynamics AX, one can create [http://msdn.microsoft.com/en-us/library/cc593549.aspx XML documentation files] that can be compiled with [http://sandcastle.codeplex.com Sandcastle] to create [http://en.wikipedia.org/wiki/Microso...iled_HTML_Help CHM help] files.


An [[media:ShellExecute.chm.zip|example]] of Dynamics AX XML documentation compiled with Sandcastle:

[[Image:ShellExecute.png]]


== Required Software ==

Microsoft .NET Framework Version 2.0, available [http://msdn.microsoft.com/netframewo...s/default.aspx here]

HTML Help Workshop available [http://msdn.microsoft.com/library/de...pDownloads.asp here]

Sandcastle available [http://sandcastle.codeplex.com/Relea...tReleases.aspx here] or [http://www.microsoft.com/downloads/d...5-696e3a4873b2 here]


== Steps ==

# Creating the XML documentation files
# Modifying the generated reflection file (reflection.org)
# Optional additions
# Compiling Sandcastle

=== Creating the XML documentation files ===

Follow the steps described in the [http://msdn.microsoft.com/en-us/library/cc654944.aspx Dynamics AX 2009 SDK] to generate the XML documentation files. Be sure to store both the documentation and reflection file in the same folder and name them as follows:

comments.xml (documentation file)

reflection.org (reflection file)

=== Modifying the generated reflection file (reflection.org) ===

In order for Sandcastle to create the table of contents and generate the html files, the following changes need to be made to the reflection file:


* Replace the first occurance of ''''

This does the same with xsl:






R:Project








The result should look similar to this:











==== Hiding other languages ====

To prevent other languages from being displayed, such as VB or C++, edit the presentation sandcastle.config file and comment out all of the undesired elements.

Example:







==== Tables ====

Tables and relations are not supported with Sandcastle, so if they are included in an AX project, then they need to be changed to one of the supported types, such as class and field.

* Replace every occurance of ''subgroup="table"'' with ''subgroup="[class|structure|interface|enumeration|delegate]"''
* Replace every occurance of ''subgroup="relation"'' with ''subgroup="[constructor|method|property|field|event]"''

Or, doing the same with xsl (this example replaces table and relation with class and field):





class


field






==== X++ language syntax title ====

For X++ one can use the C# generator since the syntax is similar. However, for the documentation to be titled as X++ rather than C#, modify shared_content.xml in the Sandcastle presentation content folder and replace C# with X++.

Example:


X++
Visual Basic
Visual Basic Usage
Visual C++



=== Compiling Sandcastle ===

[https://blogs.msdn.com/sandcastle/ar...29/682398.aspx "Creating a Chm build using Sandcastle"] walks one through the process of manually creating a chm file using Sandcastle. For AX, jump to step 5. More examples can be found in the Sandcastle examples folder under %programfiles%\Sandcastle\Examples. To simplify the process, I created [[media:RunSandcastle.zip|RunSandcastle.bat]]. Download and extract it to the XML documentation folder and then run the following command from dos to generate help in the "chm" subfolder:


[[media:RunSandcastle.zip|RunSandcastle.bat]] [Presentation] [Output file title]


Example:

C:\Temp\RunSandcastle.bat [http://blogs.msdn.com/sandcastle/arc...d-vsorcas.aspx Hana] ShellExecute


Источник: http://www.axaptapedia.com/Sandcastle