docs: Restructure BladeBridge configuration guide with practical UC namespace example

[BesikiML]

Summary

Improves the BladeBridge configuration documentation by integrating a practical example into the "Creating the custom configuration file" section, making it more actionable and easier to follow.

Changes Made

Documentation Restructuring

• Moved SQL configuration example from standalone section into "Creating the custom configuration file" section
• Added "Practical Example: Renaming Tables and Schema Mapping" subsection with:
  • Business context: UC three-level namespace paradigm
  • Step-by-step configuration instructions
  • Clear explanation of outcomes
• Removed redundant "SQL Configuration Files" section that duplicated content

Content Improvements

• Introduced example with business intent before technical details
• Demonstrates inherit_from, target_sql_file_header, and line_subst usage in context
• Shows practical schema mapping (schema01 → gold, schema02 → silver)
• Uses more formal, professional tone throughout

Linked issues

Implemented: https://github.com/databrickslabs/bladerunner/issues/619

Rationale

Previously, the SQL configuration example appeared as a separate section later in the document, disconnected from the setup instructions. This restructuring:

• ✅ Provides immediate practical value when users are setting up custom configs
• ✅ Shows the "why" (business need) alongside the "how" (configuration)
• ✅ Reduces redundancy and improves document flow
• ✅ Makes the guide more actionable for common use cases

Impact

• User Experience: Easier to follow, more intuitive learning path
• Documentation Quality: Better structure, reduced duplication
• Compatibility: No breaking changes, purely documentation improvement

Testing

• Verified markdown formatting renders correctly
• Confirmed all code blocks are properly formatted
• Checked that all cross-references are intact

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.11%. Comparing base (34d089d) to head (7b823d0).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2135   +/-   ##
=======================================
  Coverage   64.11%   64.11%           
=======================================
  Files         101      101           
  Lines        8675     8675           
  Branches      902      902           
=======================================
  Hits         5562     5562           
  Misses       2941     2941           
  Partials      172      172           

☔ View full report in Codecov by Sentry.
📢 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.

[github-actions]

✅ 51/51 passed, 5 flaky, 4m7s total

Flaky tests:

• 🤪 test_transpiles_informatica_to_sparksql (22.757s)
• 🤪 test_transpile_teradata_sql (22.524s)
• 🤪 test_transpile_teradata_sql_non_interactive[False] (20.353s)
• 🤪 test_transpiles_informatica_to_sparksql_non_interactive[False] (3.992s)
• 🤪 test_transpile_teradata_sql_non_interactive[True] (7.941s)

_{Running from acceptance #3281}

[gueniai]

@BesikiML I think this should be part of the "Creating the custom configuration file" section, we can simply state the business intent as an example.
For example:
"So let's say you want to rename your tables or ensure they follow the UC three level namespace paradigm, you can do it as follows:"

and you add everything you have here

[BesikiML]

@BesikiML I think this should be part of the "Creating the custom configuration file" section, we can simply state the business intent as an example. For example: "So let's say you want to rename your tables or ensure they follow the UC three level namespace paradigm, you can do it as follows:"

and you add everything you have here

Done