SHFB API Documentation

The Ocaramba framework utilizes Sandcastle Help File Builder (SHFB) to generate comprehensive API documentation from source code comments. This documentation provides a structured view of the framework's namespaces, classes, and methods, facilitating easier onboarding and technical reference for automation engineers.

SHFB Project Configuration

The primary documentation project is Ocaramba.Documentation.shfbproj. It is configured to build a static website representing the API surface of both the core Ocaramba libraries and their dependencies.

Key Project Properties

• Presentation Style: Uses the VS2013 style for a familiar MSDN-like navigation experience Ocaramba.Documentation/Ocaramba.Documentation.shfbproj42
• Syntax Filters: Restricted to C# to maintain focus on the framework's primary language Ocaramba.Documentation/Ocaramba.Documentation.shfbproj41
• Framework Version: Targets .NET Core/.NET Standard/.NET 5.0+ to reflect the modern cross-platform nature of the codebase Ocaramba.Documentation/Ocaramba.Documentation.shfbproj7
• Naming Method: Uses Guid for file naming to prevent issues with long file paths or special characters in class names Ocaramba.Documentation/Ocaramba.Documentation.shfbproj51
• Source Code Linking: Includes a baseSourceCodeUrl pointing to the GitHub repository to allow users to jump from documentation to the implementation Ocaramba.Documentation/Ocaramba.Documentation.shfbproj33

Documentation Sources

The builder pulls metadata and XML comments from the following functional projects:

1. OcarambaLite.csproj: The core engine containing driver logic and helpers Ocaramba.Documentation/Ocaramba.Documentation.shfbproj37
2. Ocaramba.csproj: The extended framework layer Ocaramba.Documentation/Ocaramba.Documentation.shfbproj38

Visibility and API Filtering

To keep the documentation clean, specific visibility rules are applied:

• Exposed Members: Includes InheritedMembers, Protected, and NonBrowsable items to assist developers extending the framework Ocaramba.Documentation/Ocaramba.Documentation.shfbproj68
• Namespace Filtering: The Ocaramba.Logger namespace is hidden by default (isExposed="False"), but the TestLogger class is explicitly marked as visible (isExposed="True") to ensure its logging utilities are documented for end-users while hiding internal logger plumbing Ocaramba.Documentation/Ocaramba.Documentation.shfbproj70-73

Diagram: Documentation Build Data Flow

The following diagram illustrates how source code and configuration files are processed by SHFB to produce the final API Website.

"Documentation Build Process"

Sources: Ocaramba.Documentation/Ocaramba.Documentation.shfbproj36-42 Ocaramba.Documentation/Selenium.shfbproj24-26 Ocaramba.Documentation/ContentLayout.content1-8

Selenium Dependency Documentation

The framework includes a specialized project, Selenium.shfbproj, dedicated to documenting external Selenium dependencies. This ensures that when developers browse Ocaramba's API, they have access to the underlying WebDriver documentation.

• External Sources: It explicitly targets WebDriver.dll and WebDriver.Support.dll located within the NuGet package cache (specifically targeting version 4.35.0 for .net8.0 and netstandard2.0) Ocaramba.Documentation/Selenium.shfbproj25-26
• Binding Redirection: The main documentation project includes Assembly Binding Redirection for Selenium.Support and Selenium.WebDriver to resolve version mismatches during the documentation build process Ocaramba.Documentation/Ocaramba.Documentation.shfbproj75-83

Sources: Ocaramba.Documentation/Selenium.shfbproj24-27 Ocaramba.Documentation/Ocaramba.Documentation.shfbproj74-84

Content and Versioning

Conceptual Content

Beyond auto-generated API lists, the documentation includes conceptual topics:

• ContentLayout.content: Defines the structure of the "Table of Contents" for non-API pages, setting the Welcome topic as the default Ocaramba.Documentation/ContentLayout.content1-8
• Welcome.aml: The landing page for the documentation, providing a high-level introduction to the framework and links to the GitHub Wiki for "Getting Started" guides Ocaramba.Documentation/Content/Welcome.aml1-17

Diagram: Documentation Content Structure

This diagram maps the logical documentation structure to the physical files and code namespaces.

"API Documentation Structure"

Sources: Ocaramba.Documentation/ContentLayout.content1-8 Ocaramba.Documentation/Content/Welcome.aml1-17 Ocaramba.Documentation/Ocaramba.Documentation.shfbproj70-73

Publishing Documentation

The documentation is hosted on GitHub Pages via an automated PowerShell script and CI/CD triggers.

Publishing Script Logic

The script PublishingApiDocumentationOn_gh-pages.ps1 manages the deployment to the gh-pages branch:

• Artifact Preparation: Copies the generated documentation from .\Ocaramba.Documentation\Help\ to a staging .\Help directory scripts/PublishingApiDocumentationOn_gh-pages.ps132-36
• Icon and Asset Management: Explicitly creates directory structures for branding assets, such as Help.png and Objectivity_logo_avatar.png, ensuring they are correctly placed in the gh-pages branch scripts/PublishingApiDocumentationOn_gh-pages.ps15-9
• Git Automation: If running in a tagged build (e.g., AppVEYOR_REPO_TAG), it configures Git credentials using a GithubAuthToken, clones the existing gh-pages branch, replaces the content, and pushes the new version scripts/PublishingApiDocumentationOn_gh-pages.ps111-49
• Archive Creation: Creates a .zip archive of the documentation using 7z for artifact storage scripts/PublishingApiDocumentationOn_gh-pages.ps156-58

Build Integration

• NuGet Dependencies: The project uses EWSoftware.SHFB and EWSoftware.SHFB.NET packages to enable building documentation on build agents without requiring a full Sandcastle installation Ocaramba.Documentation/Ocaramba.Documentation.shfbproj121-124
• Solution Dependency: In Ocaramba.sln, the Ocaramba.Documentation project is dependent on OcarambaLite and Ocaramba, ensuring the assemblies are built before SHFB attempts to parse them Ocaramba.sln45-50

Sources: scripts/PublishingApiDocumentationOn_gh-pages.ps11-58 Ocaramba.Documentation/Ocaramba.Documentation.shfbproj121-124 Ocaramba.sln45-50