Implementation:Microsoft LoRA Custom JS Version Selector

Overview

The custom.js file provides client-side JavaScript for the Sphinx-generated HuggingFace Transformers documentation, adding version selection, branding, Colab notebook links, and a PyTorch/TensorFlow code toggle.

Description

This JavaScript file is loaded by the Sphinx documentation site on the window.load event and executes the following UI enhancements via the onLoad() function:

addIcon(): Prepends the HuggingFace logo to the sidebar navigation.
addVersionControl(): Parses the current URL to determine the documentation version, then renders a dropdown version selector. The versionMapping dictionary maps folder names to display labels covering versions from v1.0.0 through master (stable = v4.3.x). The current version label is shown with a down arrow, and clicking it toggles the dropdown. Clicking outside dismisses it.
addCustomFooter(): Adds a footer with links to the HuggingFace blog, GitHub issue tracker, and social media (HuggingFace website, Twitter, GitHub, LinkedIn).
addGithubButton(): Inserts a GitHub Star button into the sidebar.
parseGithubButtons(): Renders GitHub buttons using an embedded minified version of the github-buttons v2.2.10 library, which fetches live star/fork/watcher counts via the GitHub API.
addHfMenu(): Inserts a top navigation bar with links to Sign In, Models, and Forum.
addColabLink(): For pages listed in the hasNotebook array (benchmarks, custom_datasets, multilingual, perplexity, preprocessing, quicktour, task_summary, tokenizer_summary, training), adds "Open in Colab" buttons with dropdown options for Mixed, PyTorch, and TensorFlow notebook variants.
platformToggle(): Detects code blocks containing both ## PYTORCH CODE and ## TENSORFLOW CODE markers and replaces them with a toggle interface allowing users to switch between PyTorch and TensorFlow code samples.

Usage

This file is automatically loaded by the Sphinx documentation build. It requires the Read the Docs Sphinx theme (sphinx-rtd-theme) and targets the CSS classes and DOM structure of that theme. It should be updated at each release by modifying stableVersion and versionMapping.

Code Reference

Source Location

examples/NLU/docs/source/_static/js/custom.js (319 lines)

Key Components

Component	Type	Description
`stableVersion`	const string	Current stable version label (`"v4.3.2"`)
`versionMapping`	const object	Maps version folder names to display labels for the dropdown
`hasNotebook`	const array	Page names that have corresponding Colab notebooks
`addIcon()`	function	Adds HuggingFace logo to sidebar
`addVersionControl()`	function	Creates version dropdown selector from URL parsing
`addCustomFooter()`	function	Adds footer with blog/issue/social links
`addGithubButton()`	function	Inserts GitHub Star button HTML
`addColabLink()`	function	Adds Open in Colab badges for notebook-enabled pages
`addHfMenu()`	function	Adds top navigation menu bar
`platformToggle()`	function	Creates PyTorch/TensorFlow code toggle for dual-framework examples
`parseGithubButtons()`	function	Minified github-buttons v2.2.10 library
`onLoad()`	function	Orchestrator called on window load; invokes all UI functions

Import / CLI Usage

<!-- In Sphinx conf.py, this file is included as a static asset -->
<!-- It is automatically loaded via: -->
<script src="_static/js/custom.js"></script>

I/O Contract

Inputs

Input	Type	Description
Current page URL	`window.location`	Parsed to determine current documentation version and page name
DOM elements	HTML	Requires `.wy-side-scroll`, `.wy-breadcrumbs-aside`, `.wy-side-nav-search .icon-home`, `footer`, and `.highlight` elements from the Sphinx RTD theme
GitHub API	HTTPS	Called by `parseGithubButtons` to fetch repository star/fork counts

Outputs

Output	Type	Description
Version dropdown	DOM element	Clickable version selector inserted into the sidebar
HuggingFace branding	DOM elements	Logo, menu bar, footer, and GitHub button
Colab links	DOM element	"Open in Colab" dropdown for notebook-enabled pages
Framework toggle	DOM elements	PyTorch/TensorFlow code sample toggle buttons

Usage Examples

// The file executes automatically on page load.
// To update for a new release, modify these two constants:

const stableVersion = "v4.4.0"   // Update to new stable version
const versionMapping = {
    "master": "master",
    "": "v4.4.0 (stable)",       // Update stable label
    "v4.3.2": "v4.3.0/v4.3.1/v4.3.2/v4.3.3",  // Move previous stable here
    // ... keep older versions
}

// To add a new notebook-enabled page, add its name to:
const hasNotebook = [
    "benchmarks",
    "custom_datasets",
    // ...
    "your_new_page"   // Add here
];

Related Pages

Environment:Microsoft_LoRA_NLU_Conda_Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment