Implementation:Pytorch Serve Custom Sphinx Directives

Overview

Custom_Sphinx_Directives provides custom Sphinx reStructuredText directives for the TorchServe documentation site. The module defines six directive classes and several helper functions that generate shields.io badges for supported devices and properties, as well as custom card layouts for the documentation gallery. These directives extend Sphinx's built-in directive system to enable rich, dynamic documentation rendering.

Field	Value
Implementation Name	Custom_Sphinx_Directives
Type	Build Tool
Workflow	Documentation_Generation
Domains	Documentation, Build_System
Knowledge Sources	Pytorch_Serve
Last Updated	2026-02-13 18:52 GMT

Description

The custom_directives.py module is loaded by Sphinx during the documentation build process. It registers custom directives that documentation authors can use in .rst files to embed device support badges, property badges, and card-based layouts without writing raw HTML.

Key Classes

Class	Lines	Description
BaseShield	55-66	Abstract base class for shield badge directives; handles common badge generation logic via shields.io API
SupportedDevices	93-109	Directive that renders device compatibility badges (e.g., CPU, GPU, XPU); parses device list and generates colored shields
SupportedProperties	112-128	Directive that renders property badges (e.g., batch_size, max_workers); parses property list and generates informational shields
CustomCardStart	182-188	Opens a card container <div> for gallery-style documentation layout
CustomCardItem	191-225	Renders individual cards with title, image, link, description, and tag badges
CustomCardEnd	228-234	Closes the card container <div> opened by CustomCardStart

Helper Functions

Function	Description
_get_cache_path(url)	Returns a local filesystem cache path for a given URL to avoid repeated downloads
_download(url, dest)	Downloads a file from a URL to a local destination path
_fetch_image(url)	Fetches an image from a URL with caching support; returns local path
_parse_devices(raw)	Parses a comma-separated device string (e.g., "cpu, gpu, xpu") into a structured list
_parse_properties(raw)	Parses a comma-separated property string into a structured list for badge generation

Badge Generation

The directives use the shields.io API to dynamically generate SVG badges. For example, a SupportedDevices directive with :devices: cpu, gpu generates two badges:

• A green badge labeled "CPU"
• A blue badge labeled "GPU"

These are fetched, cached locally, and embedded as images in the built documentation.

Code Reference

Source Location

File	Lines	Repository
docs/custom_directives.py	L1-234	pytorch/serve

Signature

class BaseShield(Directive):
    """
    Abstract base class for shield badge directives.
    Provides common logic for generating shields.io badge URLs
    and embedding them as image nodes in the Sphinx document tree.
    """
    has_content = False
    required_arguments = 0
    optional_arguments = 0

    def _make_badge_url(self, label, message, color):
        """Generate a shields.io badge URL."""
        ...

    def run(self):
        """Execute the directive and return docutils nodes."""
        ...


class SupportedDevices(BaseShield):
    """
    Sphinx directive to display device compatibility badges.

    Usage in .rst:
        .. supported-devices::
           :devices: cpu, gpu, xpu
    """
    option_spec = {
        'devices': directives.unchanged_required,
    }

    def run(self):
        """Parse devices and generate one badge per device."""
        ...


class SupportedProperties(BaseShield):
    """
    Sphinx directive to display property badges.

    Usage in .rst:
        .. supported-properties::
           :properties: batch_size, max_workers, response_timeout
    """
    option_spec = {
        'properties': directives.unchanged_required,
    }

    def run(self):
        """Parse properties and generate one badge per property."""
        ...


class CustomCardStart(Directive):
    """Opens a card gallery container div."""
    has_content = False

    def run(self):
        ...


class CustomCardItem(Directive):
    """
    Renders a single card in the documentation gallery.

    Options:
        :header: Card title text
        :image: URL or path to card image
        :link: URL the card links to
        :card_description: Description text below the title
        :tags: Comma-separated tag labels for badge rendering
    """
    option_spec = {
        'header': directives.unchanged_required,
        'image': directives.unchanged,
        'link': directives.unchanged_required,
        'card_description': directives.unchanged,
        'tags': directives.unchanged,
    }

    def run(self):
        ...


class CustomCardEnd(Directive):
    """Closes the card gallery container div."""
    has_content = False

    def run(self):
        ...

I/O Contract

Directive	Input	Output	Notes
SupportedDevices	:devices: option (comma-separated device names)	List of docutils image nodes with shields.io badges	Devices: cpu, gpu, xpu, mps, xla
SupportedProperties	:properties: option (comma-separated property names)	List of docutils image nodes with shields.io badges	Any TorchServe config property name
CustomCardStart	None	Raw HTML opening <div> node	Must be paired with CustomCardEnd
CustomCardItem	:header:, :image:, :link:, :card_description:, :tags: options	Raw HTML card element	Image is fetched and cached locally
CustomCardEnd	None	Raw HTML closing </div> node	Must be paired with CustomCardStart

Usage Examples

Example 1: Device compatibility badges in .rst

# In a .rst documentation file:
#
# .. supported-devices::
#    :devices: cpu, gpu
#
# This generates two shields.io badges:
#   [CPU | supported] in green
#   [GPU | supported] in blue

Example 2: Property badges

# In a .rst documentation file:
#
# .. supported-properties::
#    :properties: batch_size, max_workers, response_timeout
#
# Generates three informational badges for each property

Example 3: Card gallery layout

# In a .rst documentation file:
#
# .. customcardstart::
#
# .. customcarditem::
#    :header: ResNet-18 Example
#    :image: https://example.com/resnet.png
#    :link: examples/resnet18.html
#    :card_description: Image classification with ResNet-18
#    :tags: vision, classification
#
# .. customcarditem::
#    :header: BERT Example
#    :image: https://example.com/bert.png
#    :link: examples/bert.html
#    :card_description: Text classification with BERT
#    :tags: nlp, classification
#
# .. customcardend::

Example 4: Using helper functions

from docs.custom_directives import _get_cache_path, _fetch_image, _parse_devices

# Parse a device string
devices = _parse_devices("cpu, gpu, xpu")
# Returns: ['cpu', 'gpu', 'xpu']

# Get cache path for a badge URL
cache_path = _get_cache_path("https://img.shields.io/badge/CPU-supported-green")
# Returns: /path/to/.cache/shields/abc123.svg

# Fetch and cache an image
local_path = _fetch_image("https://example.com/card-image.png")

Related Pages

• Principle:Pytorch_Serve_Documentation_Generation - Documentation generation principle this module supports
• Implementation:Pytorch_Serve_BaseHandler - Handlers documented using these directives for device support badges