Installation Guide¶
This guide provides detailed instructions for setting up a complete V2X development environment. Follow these steps to install all necessary components for V2X development and documentation.
System Requirements¶
Minimum Requirements¶
- Operating System: Windows 10, macOS 10.14+, or Ubuntu 18.04+
- CPU: Intel i5 or AMD equivalent (2+ cores)
- RAM: 8GB minimum, 16GB recommended
- Storage: 10GB available space
- Network: Internet connection for package downloads
Recommended Requirements¶
- Operating System: Ubuntu 20.04+ or Windows 11
- CPU: Intel i7 or AMD Ryzen 7 (4+ cores)
- RAM: 32GB
- Storage: 50GB SSD
- Network: High-speed internet connection
Prerequisites¶
1. Python Installation¶
Windows¶
# Download Python from python.org or use winget
winget install Python.Python.3.11
# Verify installation
python --version
pip --version
macOS¶
Ubuntu/Debian¶
# Update package list
sudo apt update
# Install Python and pip
sudo apt install python3.11 python3.11-pip python3.11-venv
# Verify installation
python3.11 --version
pip3.11 --version
2. Git Installation¶
Windows¶
macOS¶
Ubuntu/Debian¶
3. Node.js (Optional, for advanced development)¶
Windows¶
macOS¶
Ubuntu/Debian¶
# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
Installation Steps¶
Step 1: Clone the Repository¶
# Clone the V2X documentation repository
git clone https://github.com/your-org/v2x-documentation.git
cd v2x-documentation
# Verify the repository structure
ls -la
Step 2: Create Virtual Environment¶
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# Verify activation (should show venv path)
which python
Step 3: Install Python Dependencies¶
Create a requirements.txt
file:
# Core MkDocs
mkdocs>=1.5.0
mkdocs-material>=9.0.0
# Extensions
pymdown-extensions>=10.0.0
mkdocs-minify-plugin>=0.7.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
# Development tools
pytest>=7.0.0
black>=23.0.0
flake8>=6.0.0
pre-commit>=3.0.0
# V2X specific libraries
asyncio-mqtt>=0.13.0
paho-mqtt>=1.6.1
websockets>=11.0.0
Install the dependencies:
# Upgrade pip first
pip install --upgrade pip
# Install requirements
pip install -r requirements.txt
# Verify installation
pip list
Step 4: Install Additional Tools¶
Docker (Optional, for containerized development)¶
# Ubuntu/Debian
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER
# macOS
brew install --cask docker
# Windows
# Download Docker Desktop from docker.com
V2X Hardware Simulator (Optional)¶
# Install V2X simulation tools
pip install v2x-simulator
# Or build from source
git clone https://github.com/v2x-simulator/v2x-simulator.git
cd v2x-simulator
pip install -e .
Step 5: Configure Development Environment¶
Set up pre-commit hooks¶
# Install pre-commit
pip install pre-commit
# Set up hooks
pre-commit install
# Run on all files
pre-commit run --all-files
Configure Git¶
# Set up Git configuration
git config user.name "Your Name"
git config user.email "your.email@example.com"
# Set up Git hooks
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
Step 6: Verify Installation¶
# Test MkDocs installation
mkdocs --version
# Test V2X simulator (if installed)
python -c "import v2x_simulator; print('V2X Simulator installed successfully')"
# Start development server
mkdocs serve
Open your browser and navigate to http://127.0.0.1:8000
to verify the documentation site is working.
Configuration Files¶
MkDocs Configuration¶
The mkdocs.yml
file is already configured with:
- Material theme with dark/light mode
- Navigation structure
- Search functionality
- Code highlighting
- MathJax support
- Git revision dates
Environment Variables¶
Create a .env
file for local development:
# V2X Configuration
V2X_SIMULATION_MODE=true
V2X_LOG_LEVEL=INFO
V2X_DATA_DIR=./data
# Development settings
DEBUG=true
FLASK_ENV=development
IDE Configuration¶
VS Code Settings¶
Create .vscode/settings.json
:
{
"python.defaultInterpreterPath": "./venv/bin/python",
"python.linting.enabled": true,
"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,
"python.formatting.provider": "black",
"editor.formatOnSave": true,
"files.associations": {
"*.md": "markdown"
}
}
PyCharm Configuration¶
- Open the project in PyCharm
- Go to File → Settings → Project → Python Interpreter
- Add the virtual environment interpreter
- Install required packages through PyCharm
Troubleshooting¶
Common Issues¶
Python Version Issues¶
# Check Python version
python --version
# If wrong version, use specific version
python3.11 --version
python3.11 -m venv venv
Permission Issues (Linux/macOS)¶
Network Issues¶
# Use alternative package index
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
# Or use conda
conda install mkdocs mkdocs-material
Port Already in Use¶
Verification Checklist¶
- Python 3.8+ installed and accessible
- Virtual environment created and activated
- All dependencies installed successfully
- MkDocs development server starts without errors
- Documentation site accessible in browser
- Git repository cloned and configured
- Pre-commit hooks installed (optional)
- V2X simulator working (optional)
Next Steps¶
After successful installation:
- Read the Quick Start Guide to create your first V2X application
- Explore V2X Technology Overview for technical details
- Check Implementation Guidelines for system design
- Review Best Practices for production deployment
Support¶
If you encounter issues during installation:
- Check the Troubleshooting section
- Review the Common Issues page
- Search existing issues in the repository
- Create a new issue with detailed error information
This installation guide provides a complete setup for V2X development. For specific platform instructions or advanced configurations, refer to the detailed documentation sections.