Skip to content

Documentation

Rice provides a documentation generator that creates Markdown files suitable for use with MkDocs or similar static site generators. The generator uses Rice's Ruby API to extract information about your extension's classes, modules, methods, and attributes.

A key feature of the documentation generator is its ability to link your Ruby API documentation to the original C++ documentation. This is done through configurable "resolvers" that know how to find documentation URLs for different types of C++ libraries.

Resolvers are configured per namespace (ie, Ruby module).

Requirements

The documentation generator requires the libxml-ruby gem:

gem install libxml-ruby

You must also enable the introspection API in your extension.

Configuration File

The rice-doc tool uses a YAML configuration file to specify the extension to document and how to resolve documentation links. This approach is used because the configuration, particularly method name mappings, can be extensive.

Here is a minimal configuration file:

extension: path/to/my_extension.so
output: ./docs/api

namespaces:
  Std:
    resolver: cppreference

Note: Ruby core types (String, Array, Integer, etc.) are automatically linked to https://docs.ruby-lang.org without any configuration.

Configuration Options

extension The path to your compiled Rice extension library. This will be a .so file on Linux, .bundle on macOS, or .so on Windows.

output The directory where generated Markdown files will be written. The directory will be created if it does not exist.

namespaces A mapping of namespace names to resolver configurations.

Running rice-doc

To generate documentation:

rice-doc config.yaml

Use rice-doc --help to see all options.

Resolvers

Resolvers are responsible for generating URLs that link your Ruby API documentation to external documentation sources. Rice includes several built-in resolvers.

Ruby Resolver (Automatic)

Ruby core classes are automatically linked to the official Ruby documentation at https://docs.ruby-lang.org. This resolver is always enabled and requires no configuration.

Classes like String, Array, Integer, Hash, and other Ruby built-in types will automatically have links to their documentation.

CppReference Resolver

The CppReference resolver links C++ standard library classes to https://en.cppreference.com.

namespaces:
  Std:
    resolver: cppreference

This resolver requires no additional configuration. It automatically looks up classes in the std namespace and generates appropriate links.

Use this resolver for the Std namespace if your extension wraps STL types like std::vector, std::map, or std::string.

Doxygen Resolver

The Doxygen resolver links classes and methods to documentation generated by Doxygen. This is useful when wrapping C++ libraries that provide Doxygen-generated documentation.

namespaces:
  MyNamespace:
    resolver: doxygen
    root: https://example.com/docs
    tagfile: https://example.com/docs/tagfile.xml
    type_mappings:
      - pattern: "^enum\\s*"
        replacement: ""
    method_mappings:
      MyNamespace::MyClass:
        ruby_method_name: cppMethodName

Configuration options:

root The base URL of the Doxygen documentation.

tagfile The URL or local path to the Doxygen tag file. Doxygen can generate this file with the GENERATE_TAGFILE option.

type_mappings (optional) A list of pattern/replacement pairs for transforming C++ type names. Each entry has:

  • pattern - A regular expression pattern (case-insensitive)
  • replacement - The replacement string (use empty string "" to remove matches)

Common uses include stripping enum or union prefixes and removing template parameters.

method_mappings (optional) A mapping of class names to method name mappings. This is used when Ruby method names differ significantly from C++ method names due to naming convention differences.

The outer key is the fully-qualified Ruby class name. The inner mapping is from Ruby method name to C++ method name.

Rice Resolver

The Rice resolver links Rice's own types (like Buffer and Pointer) to the Rice documentation.

namespaces:
  Rice:
    resolver: rice

Complete Example

Here is a complete configuration file for documenting an OpenCV wrapper:

extension: opencv
output: ./docs/api

# Note: Ruby core types are automatically linked

namespaces:
  # C++ standard library
  Std:
    resolver: cppreference

  # Rice types
  Rice:
    resolver: rice

  # OpenCV
  Cv:
    resolver: doxygen
    root: https://docs.opencv.org/4.x
    tagfile: https://docs.opencv.org/4.x/opencv.tag

    type_mappings:
      - pattern: "^enum\\s*"
        replacement: ""
      - pattern: "^union\\s*"
        replacement: ""
      - pattern: "<.*>"
        replacement: ""

    method_mappings:
      Cv:
        gaussian_blur: GaussianBlur
        hough_circles: HoughCircles
        hough_lines: HoughLines

      Cv::Mat:
        locate_roi: locateROI

      Cv::Cuda::GpuMat:
        adjust_roi: adjustROI
        locate_roi: locateROI

Method Name Mappings

When Rice wraps a C++ library, it often converts C++ method names to follow Ruby naming conventions. For example:

  • GaussianBlur becomes gaussian_blur
  • getCPUTickCount becomes get_cpu_tick_count
  • isEmpty becomes empty?

The Doxygen resolver attempts to automatically convert Ruby names back to C++ names using common patterns, but this does not always work. The method_mappings configuration allows you to specify explicit mappings for cases where automatic conversion fails.

Common patterns that require explicit mappings:

  • Acronyms: get_cpu_tick_count -> getCPUTickCount
  • Capitalized names: gaussian_blur -> GaussianBlur
  • Unconventional naming: psnr -> PSNR

Output Structure

The generator creates a directory structure that mirrors your Ruby namespace hierarchy:

docs/api/
  MyNamespace/
    index.md           # Module documentation
    MyClass.md         # Class documentation
    SubNamespace/
      AnotherClass.md

Each generated Markdown file contains:

  • Class or module name with link to C++ documentation
  • Singleton methods
  • Constructors
  • Attributes (with read/write indicators)
  • Instance methods

Method signatures include parameter names, types, and return types, with links to documentation for each type where available.