Release docs auto-generation scripts and test

PiperOrigin-RevId: 950744854 Change-Id: Ibcd9d6bd3e6ec50d5d6753b8c9516f7d31f19e5b
2026-07-20 04:11:23 -07:00
parent 78946ca94e
commit 1a33ca4ae5
7 changed files with 801 additions and 1 deletions
@@ -0,0 +1,104 @@
+# Copyright 2026 DeepMind Technologies Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Generates API for APIReference.rst."""
+
+import sys
+from typing import Dict
+
+import os
+import sys
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.dirname(os.path.dirname(_SCRIPT_DIR))
+sys.path.insert(0, os.path.join(_REPO_ROOT, 'doc', 'ext'))
+import header_reader
+
+_HEADER_FILES = [
+    'include/mujoco/mjassert.h',
+    'include/mujoco/mjdata.h',
+    'include/mujoco/mjexport.h',
+    'include/mujoco/mjmacro.h',
+    'include/mujoco/mjmodel.h',
+    'include/mujoco/mjplugin.h',
+    'include/mujoco/mjrender.h',
+    'include/mujoco/mjrfilament.h',
+    'include/mujoco/mjspec.h',
+    'include/mujoco/mjspecmacro.h',
+    'include/mujoco/mjtype.h',
+    'include/mujoco/mjui.h',
+    'include/mujoco/mjvisualize.h',
+    'include/mujoco/mjxmacro.h',
+    'include/mujoco/mujoco.h',
+]
+
+
+def generate_reference_header(
+    api: Dict[str, header_reader.ApiDefinition]) -> str:
+  """Generates the reference header file used by APIRererence.rst."""
+
+  source = """
+  // Copyright 2022 DeepMind Technologies Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// DO NOT EDIT. THIS FILE IS AUTOMATICALLY GENERATED.
+// Error: C reference not found
+// NOLINTBEGIN\n\n""".lstrip()
+
+  for value in api.values():
+    if value.c_type != 'FUNCTION':
+      source = f'{source}{value.code}'
+
+  source = f"""{source}
+//----------------------------- MJAPI FUNCTIONS --------------------------------
+"""
+
+  for value in api.values():
+    if value.c_type == 'FUNCTION':
+      source = f'{source}{value.code}'
+  source = f'{source}// NOLINTEND\n'
+  return source
+
+
+def read_headers() -> Dict[str, header_reader.ApiDefinition]:
+  """Reads API header files and generates a mapping between C tokens and C header definitions."""
+
+  api = {}
+
+  for header in _HEADER_FILES:
+    filepath = os.path.join(_REPO_ROOT, header)
+    with open(filepath, 'r', encoding='utf-8') as file:
+      api.update(header_reader.read(file.readlines()))
+  return api
+
+
+def main() -> None:
+  if len(sys.argv) > 1:
+    sys.exit('Too many command-line arguments.')
+
+  sys.stdout.buffer.write(generate_reference_header(read_headers()).encode('utf-8'))
+
+
+if __name__ == '__main__':
+  main()