Skip to content

feat: support embedded robot code in markdown and python files - #1932

Open
bhirsz wants to merge 1 commit into
mainfrom
feat/support-embedded-robot-code
Open

feat: support embedded robot code in markdown and python files#1932
bhirsz wants to merge 1 commit into
mainfrom
feat/support-embedded-robot-code

Conversation

@bhirsz

@bhirsz bhirsz commented Aug 31, 2026

Copy link
Copy Markdown
Member

Summary

Adds support for linting and formatting Robot Framework code embedded in Markdown and Python files, mirroring the embedded execution support Robot Framework added in 7.5 (Robocop does its own parsing, so it works on any RF version).

Robot code is discovered in fenced code blocks tagged ```robotframework (or ```robot):

  • Markdown files (.md, .markdown) — blocks in prose.
  • Python files (.py) — the same blocks inside docstrings (as used for runnable library examples).

A file may contain 0, 1, or many blocks. Each block is treated as an independent suite — linted and formatted on its own — while surrounding prose, fences, indentation and line endings are left untouched.

Behaviour

  • Opt-in only. Embedded files are never analyzed by default. Enable them by passing the file directly (robocop format file.md) or by adding the extension to the include patterns (--include "*.md" / config include).
  • Exact positions. Reported issues and applied fixes point at the real physical line and column in the original file (column offset is applied for indented blocks inside Python docstrings).
  • Faithful write-back. Formatting and --fix re-indent each block to its original position and preserve the file's line endings; prose is untouched and formatting is idempotent.

Implementation

  • src/robocop/embedded.py — line-based fence extractor and block model helpers.
  • EmbeddedSourceFile (source_file.py) with a build_source_file factory used by config discovery.
  • Linter integration: per-block model scan, column offsetting, raw-file-checker restriction, fix-coordinate translation.
  • Formatter: per-block format / re-indent / splice.
  • MCP tools accept the new extensions.
  • Docs: docs/user_guide/embedded_code.md.

While implementing, a line-ending bug was found and fixed: formatted blocks were emitted with LF while surrounding prose kept CRLF — the file's line ending is now detected and reapplied.

Tests

New acceptance tests under tests/embedded/ cover extraction, linter line numbers / column offsets, formatter prose-preservation, Python docstring re-indentation, idempotency, and 0/1/many blocks.

  • Full suite: 2278 passed, 87 skipped
  • ruff check / ruff format clean, mypy strict clean.

Note

Because each block is an independent suite, suite-level rules (e.g. missing suite documentation) are reported once per block. This is the intended per-block semantics.

Lint and format Robot Framework code embedded in fenced code blocks inside
Markdown (.md, .markdown) and Python (.py) files. Each block is treated as an
independent suite; physical line and column positions are preserved so
diagnostics and fixes point at the right place, and the file's indentation and
line endings are kept on write-back.

Embedded files are opt-in: pass the file directly or add its extension to the
include patterns. Adds acceptance tests and documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant