[patdhlk]

Closes #1982

extract_rst took the row of @rst as len(text[:start_idx].splitlines()). splitlines() counts a trailing partial line as a line, so any text before the start marker on its own line pushed the block one row down. This PR counts newlines instead: text[:start_idx].count("\n").

The bug was wider than the issue describes. It hit any @rst with text before it on the same line, not only one-line blocks:

case	text before @rst	before	after
one-line block, // @rst … @endrst	//	1	0
doxygen block, * @rst on its own line	/**\n * (after stripping)	2	1
@rst starting its own line	/*\n	1	1 (unchanged)

Changes

• analyse/utils.py: the one-line fix.
• test_extract_rst listed the expected row_offset but never asserted it, and its existing one-line case expected 0 when @rst sits on row 1. The test now asserts the row, that case is corrected, and a // @rst … @endrst case is added. The new case fails before the fix.
• Three snapshots had the wrong row baked in, and each corrected row matches its source:
  • test_analyse[src_dir0-src_paths0].anchors.json: dummy_1.cpp row 13 → 12, as the issue predicted.
  • test_extraction_fixture[marked_rst-single_line_rst]: /* @rst … @endrst */ on line 1, reported line 2 → 1.
  • test_extraction_fixture[marked_rst-multi_line_rst_doxygen]: * @rst on line 2, reported line 3 → 2.
• test_analyse_long_source.py: removed the comment that described this bug as a separate problem.
• Changelog entry under Unreleased. Users will see source maps in marked_content.json, and blob links built from them, move up one row for such blocks.

Checks

• uv run poe test-codelinks: 404 passed, 58 snapshots passed
• uv run poe lint: clean
• uv run poe typecheck: clean
• uv run poe docs-codelinks: build succeeded

[read-the-docs-community]

Documentation build overview

📚 sphinx-codelinks | 🛠️ Build #35000335 | 📁 Comparing 706b849 against latest (16f247c)

  🔍 Preview build  

46 files changed · + 35 added · ± 11 modified

+ Added

• minimum_config/dummy_src.html
• tests/test_analyse.html
• tests/test_analyse_config.html
• tests/test_analyse_long_source.html
• tests/test_analyse_utils.html
• tests/test_cmd.html
• tests/test_config_only_refs.html
• tests/test_missing_file_scope.html
• tests/test_need_id_ref_record.html
• tests/test_need_id_refs.html
• and 25 more...

± Modified

• changelog.html
• basics/quickstart.html
• components/analyse.html
• components/cli.html
• components/configuration.html
• components/directive.html
• components/features.html
• components/oneline.html
• components/write.html
• development/contributing.html
• and 1 more...

[chrisjsewell]

Reviewed and approved; thanks for the fix.

What I checked:

• The fix itself: row_offset = text[:start_idx].count(UNIX_NEWLINE) is the right quantity. splitlines() counted the partial line before the marker as a line, so any text before @rst on its own row pushed the block down by one; counting newlines gives the marker's row in every case (// @rst … → 0, /*\n@rst → 1, * @rst after /**\n → 1). UNIX_NEWLINE is already imported in the module.
• test_extract_rst now asserts row_offset (it listed the value before but never checked it); the corrected expected value for the existing case is right ("\n" precedes the marker there), and the new // @rst … @endrst case fails without the fix.
• The three snapshot rows each move by exactly one, and each new row matches its source line: dummy_1.cpp 13 → 12, the single-line fixture 2 → 1, the doxygen fixture 3 → 2.
• On a clean rebase onto master 5868bdd1: poe test-codelinks -rs -n 4 → 662 passed, 59 snapshots passed, 0 skipped; with utils.py reverted to master the new case and the two marked_rst snapshots fail, so the tests pin the fix. ubCode carries no marked_rst fixture, so nothing there to match.
• The changelog entry describes the user-visible effect accurately (rows in marked_content.json and the blob links built from them).

One note, not a blocker: extract_rst is about to be reworked as part of the marked-blocks design (#1885, #1898), so this function has a short remaining life; merging now still closes #1982 and keeps the row semantics the new extractor will inherit.