feat: make unsupported node types markdown-friendly before writing

[kartben]

sphinx-markdown-builder drops the node types it does not support (they only produce an "unknown node type" warning), silently losing content from the markdown renditions and the llms.txt outputs. Convert the affected node types into supported equivalents in a post-transform that runs before documents get written:

• tip and caution admonitions are mapped to hint and attention, which render as markdown boxes with a similar meaning
• generic admonitions and sidebars become a bold title followed by their content
• figure captions and legends are turned into regular (emphasized) content
• abbreviations keep their text, so words are no longer removed from the middle of sentences

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7949f39f-411b-489b-9c72-3c8362dcec2e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[jacobtomlinson]

I think this is a great improvement, but I feel this should probably be contributed to the markdown builder, not here.

I suggest you open a PR there to add support for these things. Then if they are not accepted or don't get reviewed we can think about adding this shim here until they do support it upstream.

One thing to consider would be if we added this, and then support was added upstream, how would we handle this?

[codecov-commenter]

Codecov Report

❌ Patch coverage is 57.40741% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.96%. Comparing base (21647d2) to head (a7974a8).
⚠️ Report is 23 commits behind head on main.

Files with missing lines	Patch %	Lines
src/sphinx_llm/markdown_builder.py	20.68%	23 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #134       +/-   ##
===========================================
+ Coverage   81.89%   91.96%   +10.07%     
===========================================
  Files           4       10        +6     
  Lines         624     2252     +1628     
  Branches       87      217      +130     
===========================================
+ Hits          511     2071     +1560     
- Misses         84      134       +50     
- Partials       29       47       +18     

Flag	Coverage Δ
unittests	91.96% <57.40%> (+10.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[kartben]

I think this is a great improvement, but I feel this should probably be contributed to the markdown builder, not here.

I suggest you open a PR there to add support for these things. Then if they are not accepted or don't get reviewed we can think about adding this shim here until they do support it upstream.

This makes perfect sense, thanks for the prompt feedback!

[kartben]

I suggest you open a PR there to add support for these things. Then if they are not accepted or don't get reviewed we can think about adding this shim here until they do support it upstream.

opened liran-funaro/sphinx-markdown-builder#63