Motrixlab/docs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the documentation project for MotrixSim, a high-performance physics simulation engine for multibody dynamics and robotics simulation. The documentation is built using Sphinx and targets both Chinese and English audiences.

Key Commands

Building Documentation

• Build HTML: make html or sphinx-build -b html source build/html
• Clean build: make clean followed by make html
• Serve locally: python -m http.server 8000 -d build/html
• Watch mode: Use sphinx-autobuild source build/html --host 0.0.0.0 --port 8000

Development Tools

• Check links: make linkcheck
• Build PDF: make latexpdf (requires LaTeX)
• Build single HTML: make singlehtml
• Build EPUB: make epub

Documentation Structure

Source Organization

• source/: Main documentation source files
  • index.md: Landing page with project overview and videos
  • user_guide/: User documentation and tutorials
  • api_reference/: API documentation and reference
  • en/: English language content
  • zh_CN/: Chinese language content
  • _static/: Static assets (images, videos, CSS, JS)

User Guide Structure

• getting_started/: Installation and quick start guides
• overview/: Project overview and comparisons
• kinematics/: Kinematics documentation (joints, bodies, sensors, etc.)
• main_function/: Core functionality documentation
• render/: Rendering and visualization documentation

API Reference Structure

• core/: Core API modules
• ik/: Inverse kinematics API
• rendering/: Rendering and visualization API
• low/: Low-level API (excluded from main documentation)

Build Configuration

Sphinx Configuration (conf.py)

• Theme: PyData Sphinx Theme with custom branding
• Extensions:
  • sphinx.ext.autodoc (API documentation from docstrings)
  • sphinx.ext.napoleon (NumPy/Google style docstrings)
  • sphinx.ext.autosummary (automated summaries)
  • myst_parser (Markdown support)
  • sphinx-design (design components)
  • sphinx_copybutton (code copy functionality)
• Language Support: Chinese (zh_CN) and English with automatic content copying
• Autodoc: Automatic API documentation generation from Python docstrings

Dependencies

Documentation dependencies are managed in the parent pyproject.toml:

docs = [
    "sphinx",
    "autodocsumm",
    "pydata-sphinx-theme",
    "myst-parser",
    "sphinx-copybutton",
    "sphinx-subfigure",
    "sphinxcontrib-video",
    "sphinx-togglebutton",
    "sphinx-design",
]

Content Guidelines

Documentation Style

• Primary Language: Chinese (zh_CN) with English translations
• Format: Markdown (.md) files using MyST parser
• Code Examples: Include practical code examples with proper syntax highlighting
• API Documentation: Use NumPy/Google style docstrings for autodoc generation

Media and Assets

• Videos: Embedded using sphinxcontrib-video extension
• Images: Stored in _static/images/ with poster images for videos
• Static Files: Custom CSS and JavaScript in _static/ directory
• Logos: Light and dark theme variants available

Multilingual Support

• Default Language: Chinese (zh_CN)
• Content Copying: Automatic copying of language-specific content during build
• Theme: Supports both light and dark themes with appropriate logos

Development Workflow

Adding New Documentation

1. Create Markdown files in appropriate directory (user_guide/ or api_reference/)
2. Follow existing structure and naming conventions
3. Update table of contents in relevant index.md files
4. Test build locally before committing

API Documentation

1. Write docstrings in Python source code using NumPy/Google style
2. Use autodoc directives to generate API documentation
3. Organize API docs by functional modules
4. Include examples and usage notes

Building and Testing

1. Always build locally before committing: make html
2. Check for broken links: make linkcheck
3. Verify multilingual content works correctly
4. Test all embedded media and interactive elements

File Naming Conventions

• Use lowercase with underscores for file names
• Index files should be named index.md
• API documentation files should match module names
• Media files should be descriptive and use appropriate extensions

Integration Notes

• This documentation project is part of the larger motrixsim-py package
• The build system automatically detects and documents the motrixsim package
• Documentation is deployed to ReadTheDocs at https://motrixsim.readthedocs.io
• Source code is hosted at https://github.com/Motphys/motrixsim-docs