There are numerous code layout options in the options file.
################################################################################
# <Layout settings for the generated python stub code>
################################################################################
# <show the original location and or signature of elements as a comment>
original_location_flag_show = False
# if showing location, how many parent folders shall be shown
# (if -1, show the full path)
original_location_nb_parent_folders = 0
# If True, the complete C++ original signature will be show as a comment in the python stub (pyi)
original_signature_flag_show = False
# Size of an indentation in the python stubs
python_indent_size = 4
python_ident_with_tabs: bool = False
# Insert as many empty lines in the python stub as found in the header file, keep comments layout, etc.
python_reproduce_cpp_layout: bool = True
# The generated code will try to adhere to this max length (if negative, this is ignored)
python_max_line_length = 80
# Strip (remove) empty comment lines
python_strip_empty_comment_lines: bool = False
# Run black formatter
python_run_black_formatter: bool = False
python_black_formatter_line_length: int = 88
################################################################################
# <Layout settings for the C++ generated pydef code>
################################################################################
# Spacing option in C++ code
cpp_indent_size: int = 4
cpp_indent_with_tabs: bool = FalseWe demonstrate some of them below:
import litgen
from litgen.demo import litgen_demo
options = litgen.LitgenOptions()
cpp_code = """
int add(int a, int b); // Adds two numbers
"""
options.cpp_indent_with_tabs = True # The C++ code will be indented with
options.cpp_indent_size = 1 # one tab
options.python_indent_size = 2 # The python code will be indented with 2 spaces
options.python_run_black_formatter = False # (if black is disabled)
options.original_signature_flag_show = True # We will show the original C++ signatures in the python stubs
litgen_demo.demo(options, cpp_code, show_pydef=True)Comments and docstrings¶
litgen keeps the comments of the C++ header in the Python stub. A comment that documents a declaration becomes its docstring: in the stub, and in __doc__ at runtime. The other comments stay as standalone comments in the stub.
For a declaration (a function, a class, a member, an enum value):
A comment at the end of its line documents it.
A comment on the lines directly above it documents it. When the declaration also has an end-of-line comment, the end-of-line comment wins, and the comment above stays standalone.
A comment followed by an empty line is standalone: write section titles this way.
A comment directly above several declarations of the same kind, on consecutive lines, is a group comment: it stays standalone.
import litgen
from litgen.demo import litgen_demo
options = litgen.LitgenOptions()
cpp_code = """
// Drawing functions
// (a comment followed by an empty line is standalone: write section titles this way)
// Draws a line (a comment directly above a function documents it)
void DrawLine(float x1, float y1, float x2, float y2);
void DrawPoint(float x, float y); // Draws a point (an end-of-line comment documents the function)
// Circles (a comment above several functions on consecutive lines is a group comment)
void DrawCircle(float x, float y, float radius);
void FillCircle(float x, float y, float radius);
"""
litgen_demo.demo(options, cpp_code)Headers that document each declaration¶
A header that documents each declaration often writes the comment on the line above when the declaration is long, and at the end of the line when it fits. By default, litgen reads the comment above the first of two consecutive declarations as a group comment, as it does for the section titles of imgui.h:
// Widgets: Trees
IMGUI_API bool TreeNode(const char* label);
IMGUI_API bool TreeNode(const char* str_id, const char* fmt, ...); // helper variation to ...For such a header, set options.srcmlcpp_options.comment_above_is_doc_when_next_has_eol_comment = True. The comment above a declaration then documents it when the next declaration has an end-of-line comment. In this header, end each group comment with an empty line, like the section title below. When the next declaration has no end-of-line comment, the comment above is still a group comment.
Below, without the option, set_current_editor would have no docstring.
options = litgen.LitgenOptions()
options.srcmlcpp_options.comment_above_is_doc_when_next_has_eol_comment = True
cpp_code = """
// Editor context
// (a group comment ends with an empty line)
// Makes this editor the current one: all the other functions apply to the current editor
void SetCurrentEditor(EditorContext* ctx);
EditorContext* GetCurrentEditor(); // The current editor
"""
litgen_demo.demo(options, cpp_code)