Sandcastle Document Project

Creating a project format and layout for the Sandcastle documentation as supported by the Sandcastle Assist builders is a little bit “difficult” in the MSBuild system format, especially supporting the documentation groups. We wished for a named item group, but this is not supported by the MSBuild system.

This blog is about the current project format and layout under considering and review. We present our thoughts for others to review and comment.

A large project of three conceptual groups and three references groups is shown below (in Sandcastle Workshop):

Project File Extension

The project extensions being considered are

1. *.sandproj, derived from Sandcastle + Project.
2. *.docproj, the desired extension, since it is purely documentation project. This is, however, too close to the DocProject name, which is an existing Sandcastle GUI frontend. Dropped this extension.

Other alternatives are
Sandcastle Assist derived: *.satproj, *.sanaproj, *.sasproj, *.sassproj, or
Sandcastle Workshop derived: *.swkpproj, *.swpproj, *.skpproj etc.

The current preference is *.sandproj.

Project Property Pages (and Properties Folder Contents)

We are considering six project property or settings pages, including two pages, Application and Build Events found in C# and VB.NET projects.

Since this is related to the Properties Folder in the project shown, we expand that tree node:

The pages and comments are listed in the table below:

Name	Requirements	Comments	Destination
Application	Required	Similar to C#/VB.NET projects, except less contents.	Project file.
Build Events	Required	As in C#/VB.NET projects, custom build steps.	Project file.
Sandcastle	Required	For build settings and groups. This is the actual project file, will give us more control and portability.	Settings.project file.
Formats	Required	Settings for all the output formats supported by the build system.	Settings.formats file.
Contents	Optional, created when required similar to Resources page in C#/VB.NET.	This will define global or common contents for all groups.	Settings.contents file. The various contents are document.* files shown above.
Table Of Contents	Optional, created when required similar to the Resources page in C#/VB.NET.	This is custom or user-defined final or combined table of contents for the whole project.	Settings.toc file.

Global or Common Contents

These are contents shared by or common to different build groups. Since the term “shared content” has special meaning in Sandcastle, we will avoid using that and instead use common contents here. These contents may be a single file content, a folder content (set of files/resources) or both.

Note the following about the common files and folders

• Any file or folder names can be used, those used in this section are just for illustrations, but are recommended for consistent project layouts.
• A multiple number of each contents file or folder can be used.
• All the common folder and file contents are optional.
• In cases where the folder contents are defined in a file, we recommend having the definition file outside the folder, since the folder itself may contain several files as in media folder, making it difficult to easily access the definition file.

Now, below are the supported folder and file contents types:

1. Global or Common File Contents (contents defined by file)
   

   File Name	Comments
   Document.biblio	For bibliography content support.
   Document.maths	For mathematical equations or formula gallery or repository content support.
   Document.media	For media (images, video etc) support. Related Folder: Media
   Document.samples	For samples content support. Related Folder: Samples
   Document.tokens	For Sandcastle tokens support.
   Document.snippets	For XML-based code snippet support. NOTE: This format is different from the Snippets folder contents, a direct source code snippet repository.

2. Global or Common Folder Contents (contents defined by folder)
   

   Folder Name	Comments
   Samples	For samples contents support. Contents must be defined in *.samples file.
   Media	For media contents support. Contents must be defined in *.media file.
   Snippets	For snippets contents support. The contents here are actual source codes (say C#, VB.NET), and different from the XML-based snippets defined by the *.snippets files.
   Styles	Modified/Customized Sandcastle styles, Modified/Customized Sandcastle Assist styles, User-defined styles, etc
   Scripts	Modified/Customized Sandcastle scripts, Modified/Customized Sandcastle Assist scripts, User-defined scripts, etc
   Images	User images, may be used by scripts/styles or for logo etc.

Build or Documentation Groups

A valid project requires at least a reference and/or conceptual group. Contents in a group’s folder are recommended to be used exclusively by the group.

Conceptual Group

A project may have zero or more conceptual group with the possible contents shown in the diagram below:

Folders Contents:

Name	Requirements	Comments
Images	Optional	User-defined images
Media	Required	For media contents for the conceptual topics. Contents must be defined in the *.media file.
Samples	Optional	For samples contents, must be defined in the *.samples file.
Scripts	Optional	User-defined and/or customized scripts.
Snippets	Optional	For snippets contents support.
Styles	Optional	User-defined and/or customized styles.
Topics	Required	For the conceptual topic files.
Transforms	Optional	Extended and/or customized transforms. The contents must be defined in the *.transforms file.

File Contents:

File Name	Requirements	Comments
Conceptual.cgroup	Required	This defines the conceptual group and the various contained contents and settings.
Conceptual.biblio	Optional	For bibliography contents.
Conceptual.config	Optional	For customized conceptual configurations.
Conceptual.filters	Optional	For topic and related filters.
Conceptual.maths	Optional	For mathematical gallery contents support.
Conceptual.media	Required	For media contents support.
Conceptual.samples	Optional	For samples contents support.
Conceptual.snippets	Optional	For XML-based snippets support.
Conceptual.ctoc	Required	For conceptual table of contents.
Conceptual.tokens	Optional	For tokens contents support.
Conceptual.transforms	Optional	For customized and/or user-defined transforms.

References Group

A project may have zero or more API references group with the possible contents shown in the diagram below:

Folders Contents:

Name	Requirements	Comments
Comments	Required	For the XML documentation comments extracted by compiler.
Dependencies	Required	For dependent references used by the main reference assemblies being documented.
Images	Optional	User-defined images
Media	Optional	For media contents for the references. Contents must be defined in the *.media file.
References	Required	For the main reference assemblies to be documented.
Samples	Optional	For samples contents, must be defined in the *.samples file.
Scripts	Optional	User-defined and/or customized scripts.
Snippets	Optional	For snippets contents support.
Styles	Optional	User-defined and/or customized styles.
Transforms	Optional	Extended and/or customized transforms. The contents must be defined in the *.transforms file.

File Contents:

File Name	Requirements	Comments
Reference.rgroup	Required	This defines the references group and the various contained contents and settings.
Reference.config	Optional	For customized references configurations.
Reference.filters	Optional	For topic and related filters.
Reference.maths	Optional	For mathematical gallery contents support.
Reference.media	Optional	For media contents support.
Reference.samples	Optional	For samples contents support.
Reference.snippets	Optional	For XML-based snippets support.
Reference.rtoc	Optional	For user-defined table of contents.
Reference.tokens	Optional	For tokens contents support.
Reference.transforms	Optional	For customized and/or user-defined transforms.

Revisions

1. January 04, 2010

• Changed the conceptual table of content extension to *.ctoc to make it easier for the content editors.
• Changed the references user-defined table of contents to *.rtoc to make it easier for the content editors.

2. January 04, 2010

• Dropped the *.docproj project extension consideration.
• Promoted the *.sandproj as the preferred project extension.

Conclusion

The Sandcastle Assist aims to provide a complete documentation system, and this project structure is rather complex. However, with project templates and other utilities, we can achieve the ease of use required to hide the complexity.