API Documentation and NuGet Publishing

This page outlines the processes and configurations used by the Ocaramba framework to generate its technical API documentation and distribute its libraries via NuGet. The project utilizes Sandcastle Help File Builder (SHFB) for documentation generation and a structured set of .csproj and metadata configurations for package management.

API Documentation Generation

Ocaramba generates its API documentation using Sandcastle Help File Builder (SHFB). The documentation is centralized in the Ocaramba.Documentation project and is configured to produce a web-based help system.

SHFB Project Configuration

The primary documentation project is Ocaramba.Documentation.shfbproj Ocaramba.Documentation/Ocaramba.Documentation.shfbproj1-131 It aggregates documentation sources from the core framework projects:

• OcarambaLite.csproj Ocaramba.Documentation/Ocaramba.Documentation.shfbproj37
• Ocaramba.csproj Ocaramba.Documentation/Ocaramba.Documentation.shfbproj38

The project uses the VS2013 presentation style Ocaramba.Documentation/Ocaramba.Documentation.shfbproj42 and targets C# syntax filters Ocaramba.Documentation/Ocaramba.Documentation.shfbproj41 To maintain a clean public API, visibility filters are applied; for instance, while the Ocaramba.Logger namespace is generally hidden, the TestLogger class is explicitly exposed Ocaramba.Documentation/Ocaramba.Documentation.shfbproj70-73 The project also defines a global FrameworkVersion string as .NET Core/.NET Standard/.NET 5.0+ Ocaramba.Documentation/Ocaramba.Documentation.shfbproj7

External Dependencies

To provide a complete reference, Ocaramba includes documentation for its primary dependency, Selenium WebDriver. This is handled via Selenium.shfbproj Ocaramba.Documentation/Selenium.shfbproj1-59 which points to the WebDriver.dll and WebDriver.Support.dll located in the NuGet package cache Ocaramba.Documentation/Selenium.shfbproj25-26

Documentation Deployment

The documentation layout is defined in ContentLayout.content Ocaramba.Documentation/Ocaramba.Documentation.shfbproj114 and includes conceptual topics like the "Welcome" page Ocaramba.Documentation/Ocaramba.Documentation.shfbproj110 During the CI/CD process, these files are compiled into a static website using the HelpFileFormat set to Website Ocaramba.Documentation/Ocaramba.Documentation.shfbproj40 and published to GitHub Pages.

For details, see SHFB API Documentation.

Sources:

• Ocaramba.Documentation/Ocaramba.Documentation.shfbproj1-131
• Ocaramba.Documentation/Selenium.shfbproj1-59

---

NuGet Package Structure

Ocaramba is distributed as two distinct NuGet packages to cater to different user needs: Ocaramba (the full framework) and OcarambaLite (the core engine).

Package Definitions

The solution contains two main library projects that correspond to these packages:

1. OcarambaLite: The foundational library containing the core engine, with no external driver dependencies OcarambaLite/OcarambaLite.csproj6
2. Ocaramba: A wrapper package that includes additional dependencies like SQL client and browser drivers Ocaramba/Ocaramba.csproj31-37 It explicitly references the lite version as a project dependency Ocaramba/Ocaramba.csproj55

Versioning and Publishing

The framework versioning is managed centrally. The build process ensures deterministic restores using RestorePackagesWithLockFile Ocaramba/Ocaramba.csproj64-65 and packages.lock.json files Ocaramba/packages.lock.json1-10 It includes SourceLink for better debugging experiences Ocaramba/Ocaramba.csproj38 and StyleCop.Analyzers to enforce code quality Ocaramba/Ocaramba.csproj39-42

The release pipeline is responsible for:

• Packing the projects into .nupkg (binary) and .snupkg (symbols) files Ocaramba/Ocaramba.csproj21-22
• Setting the version metadata (currently defaulted to 1.0.0 in source) Ocaramba/Ocaramba.csproj14
• Including necessary assets like icon.png Ocaramba/Ocaramba.csproj27 and README.md Ocaramba/Ocaramba.csproj28-30

For details, see NuGet Package Structure.

Sources:

• Ocaramba/Ocaramba.csproj1-66
• OcarambaLite/OcarambaLite.csproj1-63
• Ocaramba/packages.lock.json1-10

---

Code to Documentation Mapping

The following diagram illustrates how the source code projects and external DLLs are transformed into the final documentation website via the SHFB build process.

API Documentation Pipeline

Sources:

• Ocaramba.Documentation/Ocaramba.Documentation.shfbproj36-40
• Ocaramba.Documentation/Ocaramba.Documentation.shfbproj110-114
• Ocaramba.Documentation/Selenium.shfbproj24-27

---

Release Pipeline Overview

The publishing of documentation and packages is integrated into the framework's build system.

Build and Pack Workflow

Component	Responsibility	Source Entity
Documentation Source	Defines which projects are documented	DocumentationSource Ocaramba.Documentation/Ocaramba.Documentation.shfbproj36-39
NuGet Package	Full framework with drivers	Ocaramba.csproj Ocaramba/Ocaramba.csproj6
Lite Package	Core framework engine	OcarambaLite.csproj OcarambaLite/OcarambaLite.csproj6
SHFB Engine	Compiles XML comments into HTML	EWSoftware.SHFB Ocaramba.Documentation/Ocaramba.Documentation.shfbproj123
Symbol Package	Debugging information for NuGet	.snupkg Ocaramba/Ocaramba.csproj22

Sources:

• Ocaramba.Documentation/Ocaramba.Documentation.shfbproj122-127
• Ocaramba/Ocaramba.csproj15-22
• Ocaramba.sln45-50