Release docs auto-generation scripts and test
PiperOrigin-RevId: 950744854 Change-Id: Ibcd9d6bd3e6ec50d5d6753b8c9516f7d31f19e5b
This commit is contained in:
Yuval Tassa
committed by
Copybara-Service
Copybara-Service
parent
78946ca94e
commit
1a33ca4ae5
@@ -0,0 +1,238 @@
|
||||
# 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 MJCF schema using dropdown directives for XMLreference.rst.
|
||||
|
||||
Generates XMLschema.rst by reading xml_native_reader.cc and producing
|
||||
nested dropdown directives with list-table for attributes.
|
||||
"""
|
||||
|
||||
import copy
|
||||
import sys
|
||||
|
||||
import os
|
||||
|
||||
# Map symbols to icons:
|
||||
# ! = required element, can appear only once -> star (prominent, required)
|
||||
# ? = optional element, can appear only once -> dot (minimal, single)
|
||||
# * = optional element, can appear many times -> None (no icon, most common)
|
||||
# R = optional element, can appear many times recursively -> sync (recursive)
|
||||
SYMBOL_TO_ICON = {
|
||||
'!': 'star',
|
||||
'?': 'dot',
|
||||
'*': None,
|
||||
'R': 'sync',
|
||||
}
|
||||
|
||||
ELEMENT_ORDER = [
|
||||
'mujoco',
|
||||
'option',
|
||||
'compiler',
|
||||
'size',
|
||||
'statistic',
|
||||
'asset',
|
||||
'body',
|
||||
'deformable',
|
||||
'contact',
|
||||
'equality',
|
||||
'tendon',
|
||||
'actuator',
|
||||
'sensor',
|
||||
'keyframe',
|
||||
'visual',
|
||||
'default',
|
||||
'custom',
|
||||
'extension',
|
||||
]
|
||||
|
||||
# Special display names for elements (when different from the element name)
|
||||
ELEMENT_DISPLAY_NAME = {
|
||||
'body': '(world)body',
|
||||
}
|
||||
|
||||
|
||||
def generate_dropdown(
|
||||
element_name: str,
|
||||
symbol: str,
|
||||
link_name: str,
|
||||
attributes: list[str],
|
||||
links: list[str],
|
||||
level: int,
|
||||
is_top_level: bool = False,
|
||||
) -> str:
|
||||
"""Generate a dropdown directive for an element with its attributes."""
|
||||
indent = ' ' * level
|
||||
output = ''
|
||||
|
||||
display_name = ELEMENT_DISPLAY_NAME.get(element_name, element_name)
|
||||
icon = SYMBOL_TO_ICON.get(symbol)
|
||||
# Element name is a :ref: link. Icon/macro goes on the right side.
|
||||
# Use |*| for * elements (even though it's empty) for future flexibility.
|
||||
element_link = f':ref:`{display_name}<{link_name}>`'
|
||||
if icon:
|
||||
title = f'{element_link} :octicon:`{icon}`'
|
||||
else:
|
||||
title = f'{element_link} |*|'
|
||||
output += f'{indent}.. dropdown:: {title}\n'
|
||||
if is_top_level:
|
||||
output += f'{indent} :open:\n'
|
||||
output += '\n'
|
||||
|
||||
content_indent = indent + ' '
|
||||
|
||||
# Responsive grid for attributes (2-3-4-4: mobile-tablet-desktop-large)
|
||||
if attributes:
|
||||
output += f'{content_indent}.. grid:: 2 3 4 4\n'
|
||||
output += f'{content_indent} :gutter: 0\n'
|
||||
output += '\n'
|
||||
|
||||
for attr in attributes:
|
||||
att_link_name = f'{link_name}-{attr}'
|
||||
if att_link_name not in links:
|
||||
raise ValueError(
|
||||
f'Link for attribute {att_link_name} not found, update'
|
||||
' XMLreference.rst'
|
||||
)
|
||||
output += f'{content_indent} .. grid-item::\n'
|
||||
output += f'{content_indent} :ref:`{attr}<{att_link_name}>`\n'
|
||||
output += '\n'
|
||||
|
||||
output += '\n'
|
||||
return output
|
||||
|
||||
|
||||
def generate() -> str:
|
||||
"""Generates XMLschema.rst by parsing xml_native_reader.cc.
|
||||
|
||||
The schema is defined in xml_native_reader.cc as a nested structure called
|
||||
MJCF[nMJCF]. This function parses that structure and generates nested
|
||||
dropdown directives with list-tables for attributes.
|
||||
|
||||
Returns:
|
||||
RST content with nested dropdown directives for the MJCF schema.
|
||||
"""
|
||||
script_dir = os.path.dirname(os.path.abspath(__file__))
|
||||
repo_root = os.path.dirname(os.path.dirname(script_dir))
|
||||
filepath = os.path.join(repo_root, 'src', 'xml', 'xml_native_reader.cc')
|
||||
xmlfile = os.path.join(repo_root, 'doc', 'XMLreference.rst')
|
||||
|
||||
# Collect all link targets from XMLreference.rst for validation.
|
||||
links = []
|
||||
with open(xmlfile, 'r', encoding='utf-8') as file:
|
||||
for line in file:
|
||||
if line.startswith('.. _'):
|
||||
links.append(line.strip()[4:-1])
|
||||
|
||||
output = """..
|
||||
DO NOT EDIT. THIS FILE IS AUTOMATICALLY GENERATED.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="schema-controls" style="margin-bottom: 1em;">
|
||||
<button onclick="document.querySelectorAll('.schema-small details').forEach(d => d.open = true)" class="sd-btn sd-btn-outline-primary sd-btn-sm">Expand All</button>
|
||||
<button onclick="document.querySelectorAll('.schema-small details details').forEach(d => d.open = false)" class="sd-btn sd-btn-outline-secondary sd-btn-sm" style="margin-left: 0.5em;">Collapse All</button>
|
||||
</div>
|
||||
|
||||
"""
|
||||
|
||||
with open(filepath, 'r', encoding='utf-8') as file:
|
||||
to_strip = {' ', '{', '}', '"'}
|
||||
|
||||
# Process each top-level element in a specific order for consistent output.
|
||||
for top_element in ELEMENT_ORDER:
|
||||
level = 0
|
||||
element: list[str] = []
|
||||
parent = ['', '', '', '', ''] # Track parent elements for link names.
|
||||
found_element = False
|
||||
file.seek(0)
|
||||
|
||||
# Skip to the MJCF schema definition in the C++ source.
|
||||
for line in file:
|
||||
if 'std::vector<const char*> MJCF[nMJCF] = {' in line.strip():
|
||||
break
|
||||
|
||||
# Parse the schema structure.
|
||||
for line in file:
|
||||
if line.strip().endswith('};'):
|
||||
break # End of schema definition.
|
||||
|
||||
# Track nesting level using angle brackets in the C++ source.
|
||||
if '<' in line:
|
||||
level += 1
|
||||
continue
|
||||
if '>' in line:
|
||||
level -= 1
|
||||
continue
|
||||
|
||||
# Parse element definition from the line.
|
||||
line_is_done = 1 if '}' in line else 0
|
||||
line_copy = copy.copy(line)
|
||||
for item in to_strip:
|
||||
line_copy = line_copy.replace(item, '')
|
||||
element += [item for item in line_copy.split(',') if item != '\n']
|
||||
|
||||
# Determine if this element belongs to the current top-level element.
|
||||
outer_level = level == 0 and top_element == 'mujoco'
|
||||
top_level = level == 1 and element and top_element == element[0]
|
||||
sub_level = level > 1 and top_element == parent[2]
|
||||
level_is_correct = outer_level or top_level or sub_level
|
||||
|
||||
if found_element and not level_is_correct:
|
||||
break # Done with this top-level element.
|
||||
found_element = level_is_correct
|
||||
|
||||
# Generate dropdown for completed element definition.
|
||||
if line_is_done and level_is_correct:
|
||||
# Link name: top-level uses element name, nested uses parent-child.
|
||||
link_name = element[0]
|
||||
if level > 1:
|
||||
link_name = parent[level] + '-' + element[0]
|
||||
if link_name not in links:
|
||||
raise ValueError(
|
||||
f'Link for element {link_name} not found, update'
|
||||
' XMLreference.rst'
|
||||
)
|
||||
attributes = element[2:] # First two items are name and symbol.
|
||||
|
||||
# Adjust indentation level for RST output.
|
||||
dropdown_level = 0 if level == 0 else (1 if level == 1 else level)
|
||||
is_top_level = level == 0
|
||||
output += generate_dropdown(
|
||||
element[0],
|
||||
element[1],
|
||||
link_name,
|
||||
attributes,
|
||||
links,
|
||||
dropdown_level,
|
||||
is_top_level,
|
||||
)
|
||||
|
||||
# Track parent elements for building nested link names.
|
||||
if line_is_done:
|
||||
if level < 4:
|
||||
parent[level + 1] = element[0]
|
||||
element = []
|
||||
|
||||
return output
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if len(sys.argv) > 1:
|
||||
sys.exit('Too many command-line arguments.')
|
||||
sys.stdout.buffer.write(generate().encode('utf-8'))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user