chore: release v0.0.1
This commit is contained in:
motphys-developers
142
docs/CLAUDE.md
Normal file
142
docs/CLAUDE.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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`:
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user