Fetch source code line links for API functions on docs client side.

PiperOrigin-RevId: 692115441
Change-Id: Ifbedf6a4998000f99e2275cb43293b3050daf0ee

doc/APIreference/APIfunctions.rst

@@ -1,3 +1,8 @@
+.. raw:: html
+
+    <div id="fetchlines"/>
+
+
 .. _API:
 
 =========

doc/changelog.rst

@@ -31,6 +31,12 @@ Bug fixes
   runtime enabling/disabling of such constraints.
 - Fixed a bug in slider-crank :ref:`transmission<geTransmission>`. The bug was introduced in 3.0.0.
 
+
+Documentation
+^^^^^^^^^^^^^
+- Function headers in the :doc:`API reference <../APIreference/APIfunctions>` now link to their source definitions
+  in GitHub.
+
 Version 3.2.4 (Oct 15, 2024)
 ----------------------------
 

doc/conf.py

@@ -159,10 +159,14 @@ pygments_dark_style = 'monokai'
 html_static_path = [
     '_static',
     'css',
+    'js',
 ]
 html_css_files = [
     'theme_overrides.css',
 ]
+html_js_files = [
+    'linenumbers.js',
+]
 
 favicons = [
     {

doc/js/linenumbers.js

@@ -0,0 +1,108 @@
+const SRCS = [
+  'xml/xml_api.cc',
+  'user/user_api.cc',
+  'user/user_init.c',
+  'user/user_vfs.cc',
+  'thread/thread_task.cc',
+  'thread/thread_pool.cc',
+  'render/render_context.c',
+  'render/render_gl2.c',
+  'render/render_gl3.c',
+  'render/render_util.c',
+  'engine/engine_derivative.c',
+  'engine/engine_io.c',
+  'engine/engine_sensor.c',
+  'engine/engine_callback.c',
+  'engine/engine_collision_driver.c',
+  'engine/engine_core_constraint.c',
+  'engine/engine_core_smooth.c',
+  'engine/engine_derivative_fd.c',
+  'engine/engine_forward.c',
+  'engine/engine_inverse.c',
+  'engine/engine_island.c',
+  'engine/engine_name.c',
+  'engine/engine_passive.c',
+  'engine/engine_plugin.cc',
+  'engine/engine_print.c',
+  'engine/engine_ray.c',
+  'engine/engine_setconst.c',
+  'engine/engine_solver.c',
+  'engine/engine_support.c',
+  'engine/engine_util_blas.c',
+  'engine/engine_util_container.c',
+  'engine/engine_util_errmem.c',
+  'engine/engine_util_misc.c',
+  'engine/engine_util_solve.c',
+  'engine/engine_util_spatial.c',
+  'engine/engine_util_sparse.c',
+  'engine/engine_vis_init.c',
+  'engine/engine_vis_interact.c',
+  'engine/engine_vis_state.c',
+  'engine/engine_vis_visualize.c',
+  'ui/ui_main.c',
+];
+
+class LineNumbers {
+  constructor() {
+    this.map = new Map();
+  }
+
+  static fetch(src) {
+    const url = `https://raw.githubusercontent.com/google-deepmind/mujoco/refs/heads/main/src/${src}`;
+    const request = new XMLHttpRequest();
+    return new Promise((resolve, reject) => {
+      request.onreadystatechange = () => {
+        if (request.readyState === 4) {
+          if (request.status === 200) {
+            resolve(request.responseText);
+          } else {
+            reject(request.status);
+          }
+        }
+      };
+      request.open('GET', url, true);
+      request.send();
+    });
+  }
+
+  fetchAll() {
+    let requests = [];
+    for (const src of SRCS) {
+      requests.push(LineNumbers.fetch(src).then(contents => {
+        this.processSrc(src, contents);
+      }, reason => {/* swallow error */}));
+    }
+    Promise.all(requests).then(() => {
+      const anchors = document.querySelectorAll('h3 a.reference.external');
+      for (const anchor of anchors) {
+        const url = anchor.getAttribute('href');
+        if (url.startsWith('#')) {
+          const key = url.substring(1);
+          if (this.map.has(key)) {
+            anchor.href = this.map.get(key);
+          } else {
+            console.log(`No line number found for ${key}`);
+          }
+        }
+      }
+    });
+  }
+
+  processSrc(src, contents) {
+    const lines = contents.split('\n');
+    const re = /^(const )?[a-zA-Z0-9_*]+\s(.+)\(.+[{,]$/;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].match(re)) {
+        const key = lines[i].match(re)[2];
+        this.map.set(key, `https://github.com/google-deepmind/mujoco/blob/main/src/${src}#L${i+1}`);
+      }
+    }
+  }
+}
+
+window.onload = () => {
+  if (document.getElementById('fetchlines')) {
+    let lines = new LineNumbers();
+    lines.fetchAll();
+  }
+};