Implementation:CARLA simulator Carla Doc Gen
| Knowledge Sources | |
|---|---|
| Domains | Documentation, Code Generation, API Specification |
| Last Updated | 2026-02-15 05:00 GMT |
Overview
Python script that generates Markdown API reference documentation from the CARLA Python API YML specification files.
Description
This script (doc_gen.py) reads YML API specification files (actor.yml, blueprint.yml, client.yml, etc.) and converts them into structured Markdown documentation. It defines a MarkdownFile class for building Markdown content programmatically, with methods for titles, lists, code blocks, separators, and text formatting. The script uses color-coded formatting constants (COLOR_METHOD, COLOR_PARAM, COLOR_INSTANCE_VAR, COLOR_NOTE, COLOR_WARNING) for consistent styling. It employs a regex-based hyperlink system (create_hyperlinks) that converts carla.ClassName references into clickable links. Helper functions include italic(), bold(), snipet(), and code() for text formatting. The script imports doc_gen_snipets for embedding code examples and uses the yaml library for parsing the YML source files.
Usage
Run this script from the PythonAPI/docs directory to regenerate the API reference documentation. It is part of the CARLA documentation build pipeline and should be executed whenever the YML API spec files are modified.
Code Reference
Source Location
- Repository: CARLA
- File: PythonAPI/docs/doc_gen.py
Signature
# Color constants
COLOR_METHOD = '#7fb800'
COLOR_PARAM = '#00a6ed'
COLOR_INSTANCE_VAR = '#f8805a'
COLOR_NOTE = '#8E8E8E'
COLOR_WARNING = '#ED2F2F'
QUERY = re.compile(r'([cC]arla(\.[a-zA-Z0-9_]+)+)')
def create_hyperlinks(text): ...
def create_getter_setter_hyperlinks(text): ...
def join(elem, separator=''): ...
class MarkdownFile:
def __init__(self): ...
def data(self): ...
def list_push(self, buf=''): ...
def list_pop(self): ...
def separator(self): ...
def new_line(self): ...
def text(self, buf): ...
def title(self, strongness, buf): ...
def title_html(self, strongness, buf): ...
def code_block(self, buf, language=''): ...
def prettify_doc(self, doc): ...
def italic(buf): ...
def bold(buf): ...
def snipet(name, class_key): ...
def code(buf): ...
Import
# Run from PythonAPI/docs directory:
python doc_gen.py
I/O Contract
| Input | Type | Description |
|---|---|---|
| YML files | *.yml | API specification files (actor.yml, blueprint.yml, etc.) |
| doc_gen_snipets | module | Code snippet templates for documentation |
| Output | Type | Description |
|---|---|---|
| Markdown files | *.md | Generated API reference documentation |
Usage Examples
# Generate documentation from the PythonAPI/docs directory
import os
os.chdir('PythonAPI/docs')
os.system('python doc_gen.py')
# The MarkdownFile class can also be used programmatically
from doc_gen import MarkdownFile
md = MarkdownFile()
md.title(2, 'My Section')
md.textn('Some documentation text.')
print(md.data())