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 63.56%. Comparing base (5a297d2) to head (bb2448a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2135   +/-   ##
=======================================
  Coverage   63.56%   63.56%           
=======================================
  Files         100      100           
  Lines        8503     8503           
  Branches      885      885           
=======================================
  Hits         5405     5405           
  Misses       2931     2931           
  Partials      167      167           

☔ 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, 10 flaky, 4m36s total

Flaky tests:

• 🤪 test_validate_mixed_checks (171ms)
• 🤪 test_validate_invalid_schema_path (1ms)
• 🤪 test_validate_invalid_source_tech (169ms)
• 🤪 test_validate_non_empty_tables (11ms)
• 🤪 test_validate_table_not_found (1ms)
• 🤪 test_transpiles_informatica_to_sparksql_non_interactive[False] (25.246s)
• 🤪 test_transpiles_informatica_to_sparksql (24.318s)
• 🤪 test_transpile_teradata_sql_non_interactive[True] (27.473s)
• 🤪 test_transpile_teradata_sql (9.057s)
• 🤪 test_transpiles_informatica_to_sparksql_non_interactive[True] (12.434s)

_{Running from acceptance #3152}

[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