Code Includes

This guide demonstrates the include shortcode, which lets you embed source files directly into your documentation pages.

Basic Python Include

The simplest usage includes an entire file with automatic language detection. The shortcode infers the language from the file extension.

from gdtest_code_include import Widget

# Create and configure a widget
widget = Widget("demo")
widget.configure(color="blue", size=10)

# Run the widget
result = widget.run()
print(f"Result: {result}")

Including a YAML File

The include shortcode works with any text file type. Here we include a YAML configuration file, and the language is detected automatically from the .yaml extension.

app:
  name: my-app
  version: "1.0"
  settings:
    debug: true
    log_level: info

Selecting a Line Range

You can include only specific lines from a file using the lines parameter. This is useful for highlighting a particular section without showing the entire file.

from gdtest_code_include import Widget

# Create and configure a widget

Overriding the Language

Sometimes a file extension doesn’t match the highlighting you want. Use the lang parameter to override the auto-detected language. Here we display a Python file with R syntax highlighting instead.

from gdtest_code_include import Widget

# Create and configure a widget
widget = Widget("demo")
widget.configure(color="blue", size=10)

# Run the widget
result = widget.run()
print(f"Result: {result}")