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
- *.sandproj, derived from Sandcastle + Project.
*.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.
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. |
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:
- 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: MediaDocument.samples For samples content support.
Related Folder: SamplesDocument.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. - 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, etcScripts Modified/Customized Sandcastle scripts,
Modified/Customized Sandcastle Assist scripts,
User-defined scripts, etcImages User images, may be used by scripts/styles or for logo etc.
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.
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. |
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. |
- 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.
- Dropped the *.docproj project extension consideration.
- Promoted the *.sandproj as the preferred project extension.
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.
