Sandcastle is a free Microsoft tool that automatically generates documentation from program source assemblies and XML comment files for Microsoft Visual Studio .NET development projects. The latest version of Sandcastle 2.7.2 from Microsoft is included with Help+Manual, making it possible to generate source code documentation from your .NET projects directly.
See the Source Code Documentation with Sandcastle chapter for full instructions on using Sandcastle for documenting your .NET source code.
Help+Manual cannot be used with Sandcastle Help File Builder
Please note that you cannot use the independent Sandcastle Help File Builder system or its configuration. Help+Manual actually performs similar tasks to Help File Builder, so it replaces its role in interaction with Sandcastle.
Help+Manual's installation includes the latest version of Microsoft Sandcastle. You can use your own Sandcastle installation if you wish, provided it is version 2.4 or later. However, if you wish to do this you must not select the Sandcastle option when installing the program. Help+Manual will always use its own version automatically, and it will then ignore any other installed version. (Help+Manual's version will not interfere with your own installation, if it exists.)
We strongly recommend using the bundled version of Sandcastle included with Help+Manual. It is the latest official Microsoft version and Help+Manual is optimized for it.
For more information about Sandcastle see Microsoft's Sandcastle page:
 http://msdn.microsoft.com/en-us/vstudio/bb608422.aspx
|
1.Document your source code using triple slash comments and Sandcastle XML tags.
2.Activate the XML documentation file option for your project in Visual Studio in the section. Alternatively you can also compile manually with the documentation switch /doc:comments.xml.
3.Build your .NET project or assemblies to the release version, or the version where the XML documentation file you have configured is exported.
See Configuring Your .NET Project for detailed instructions explaining how to set up your .NET project and write your comments there.
|
1.Select New Project in the menu.
2.Select Sandcastle documentation file in the Import existing documentation section in the lower half of the page.
3.Enter the name and path for your new Help+Manual project and configure the other settings as you would for an empty new project.
4.Click on Continue with Options and select your assemblies, comment files and any dependent assemblies. The comments file is the XML documentation file you configure in your .NET project. You can choose multiple files in each category. You can also set a topic status to be set for your imported topics.
5.Click on Import. Help+Manual will then run Sandcastle in the background, generate the project and import it to a Help+Manual project. Depending on the size of your programming project this may take a while. The time this takes depends on Sandcastle and the speed of your computer, not on Help+Manual.
6.When the process is finished your Sandcastle project will appear in Help+Manual for editing. You can then edit and publish it just like any normal Help+Manual project:
|
You can also update your source code documentation to the Help+Manual project you created from an earlier version.
Open the Help+Manual project and select Import in the menu instead of New Project. All the other steps are the same as described above. New topics chapters will be added to the end of the existing TOC. Updates to existing topics and chapters will be handled depending on the conflict management settings you configure for "changed topics". If you opt to overwrite the existing topics the earlier versions will be replaced.
|
