Documentation Generator

Documentation Generator#

Implementation#

class clanguru.doc_generator.CodeContent(code: str, language: str = 'c', linenos: bool = True, highlight_lines: list[int] | None = None, start_line: int | None = None)[source]#

Bases: object

class clanguru.doc_generator.DocStructure(title: str)[source]#

Bases: object

Format independent documentation structure.

class clanguru.doc_generator.DocsFormat(*values)[source]#

Bases: Enum

property format_tag: str#

Return the tag used in source comments for this format.

class clanguru.doc_generator.GTestInfo(suite: str, case: str)[source]#

Bases: object

class clanguru.doc_generator.MarkdownFlavour(*values)[source]#

Bases: Enum

class clanguru.doc_generator.MarkdownFormatter(flavour: MarkdownFlavour = MarkdownFlavour.Raw, *, jinja_raw_tags: bool = False)[source]#

Bases: OutputFormatter

Markdown output formatter for documentation.

Two flavours are supported: * Raw: plain GitHub style fenced code blocks. * Myst: MystParser extended code-block directive with options (linenos & highlight lines).

property docs_format: DocsFormat#

Return the documentation format for this formatter.

file_extension() → str[source]#

Return the file extension for the formatter.

format(doc: DocStructure) → str[source]#

Format the entire documentation structure.

format_code(content: CodeContent) → str[source]#

Format a code block.

format_code_block_myst(content: CodeContent) → str[source]#

Return a fenced code block or Myst code-block directive.

Myst format example:

```{code-block} c
:linenos:
:lineno-start: 5
:emphasize-lines: 2,4

int main() {}
```
format_table(headers: list[str], rows: list[list[str]]) → str[source]#

Format a table with headers and rows.

format_text(text: str) → str[source]#

Format a text block.

class clanguru.doc_generator.OutputFormatter[source]#

Bases: ABC

Abstract base class for output formatters.

abstract property docs_format: DocsFormat#

Return the documentation format for this formatter.

abstractmethod file_extension() → str[source]#

Return the file extension for the formatter.

abstractmethod format(doc: DocStructure) → str[source]#

Format the entire documentation structure.

abstractmethod format_code(content: CodeContent) → str[source]#

Format a code block.

abstractmethod format_table(headers: list[str], rows: list[list[str]]) → str[source]#

Format a table with headers and rows.

abstractmethod format_text(text: str) → str[source]#

Format a text block.

class clanguru.doc_generator.RSTFormatter(*, jinja_raw_tags: bool = False)[source]#

Bases: OutputFormatter

reStructuredText output formatter for documentation.

property docs_format: DocsFormat#

Return the documentation format for this formatter.

file_extension() → str[source]#

Return the file extension for the formatter.

format(doc: DocStructure) → str[source]#

Format the entire documentation structure.

format_code(content: CodeContent) → str[source]#

Format a code block.

format_table(headers: list[str], rows: list[list[str]]) → str[source]#

Format a simple grid table in reStructuredText.

format_text(text: str) → str[source]#

Format a text block.

class clanguru.doc_generator.TextContent(text: str)[source]#

Bases: object

clanguru.doc_generator.generate_doc_structure(translation_unit: TranslationUnit, docs_format: DocsFormat = DocsFormat.md) → DocStructure[source]#

Generate documentation structure from a translation unit.

Uses the CLangParser to extract functions and classes from the translation unit and creates a DocStructure object with the extracted information.

clanguru.doc_generator.generate_documentation(translation_unit: TranslationUnit, formatter: OutputFormatter, output_file: Path) → None[source]#

Generate documentation from a translation unit and write it to a file using the specified formatter.

Testing#

test_doc_generator.test_crlf_line_endings_function_body_extraction(tmp_path: Path) → None[source]#

Regression test: ensure CRLF line endings don’t truncate function bodies.

We create two identical source files differing only by newline style (LF vs CRLF) and confirm the extracted function bodies are identical.

test_doc_generator.test_crlf_line_endings_function_comment_extraction(tmp_path: Path) → None[source]#

Regression test: ensure CRLF line endings in function comments are normalized.

We create two identical source files with multi-line comments differing only by newline style (LF vs CRLF) and confirm the extracted comment content is identical and uses normalized LF line endings.

test_doc_generator.test_end_to_end_c_source_to_markdown_file(tmp_path: Path) → None[source]#

End-to-end: parse a .c file, generate a .md file, and verify its exact content.

Uses @docs (generic) and @md (format-specific) tagged blocks between /* START DOCS */ and /* END DOCS */ markers. Untagged comments are ignored. An @rst block would also be ignored when generating markdown.

Contents