Skip to content

docs: Improve discoverability of Jinja resources, filters, and schema references#1149

Merged
jsuereth merged 11 commits into
mainfrom
copilot/improve-documentation-clarity
Jan 23, 2026
Merged

docs: Improve discoverability of Jinja resources, filters, and schema references#1149
jsuereth merged 11 commits into
mainfrom
copilot/improve-documentation-clarity

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Jan 21, 2026

Documentation Improvements - All Complete ✅

All documentation improvements from the issue have been successfully completed. This PR enhances the discoverability and usability of Weaver's documentation for new and existing users.

Summary of Changes

✅ Enhanced Jinja Template Documentation

  • Added "Learning Jinja Templates" section with external tutorial links
  • Made resources more prominent in Weaver Forge README

✅ Documented Built-in Helper Functions

  • Added comprehensive section on case converters (kebab_case, snake_case, etc.)
  • Included usage examples and source code link to extensions directory

✅ Improved Schema Documentation Accessibility

  • Added semconv schema to codegen.md quick links table
  • Added weaver.yaml configuration to codegen.md quick links table
  • Schema and configuration references are now easily discoverable in docs/codegen.md where users need them during code generation work

✅ Comprehensive Filter Documentation

  • Added "Understanding Filters" section explaining:
    • Default behavior (no filter)
    • How filters transform data with raw JQ expression example
    • Common helper filters provided by Weaver
    • Filter options
    • The ctx variable and its interaction with filters

Files Modified

  • docs/codegen.md - Added 130+ lines of documentation with relative links, quick reference table, and raw JQ expression examples
  • README.md - Maintained concise, action-oriented structure per original design
  • crates/weaver_forge/README.md - Enhanced with relative source link to extensions directory

Note: All markdown links use relative paths for better maintainability. Schema and configuration references are located in docs/codegen.md where users actively work with them, keeping the README focused on quick navigation to detailed documentation.

Original prompt

This section details on the original issue you should resolve

<issue_title>Documentation Improvements</issue_title>
<issue_description>Based on recent user feedback, several areas of the Weaver documentation could be improved to enhance clarity and ease of use. Below is a list of suggested improvements:

  • Provide better documentation for Jinja templates. Many users may not have recent experience with Jinja, so linking to good external resources would be helpful. e.g.: 1, 2.
  • Clarify where functions like kebab_case come from and document other built-in helper functions available in Weaver. Ideally, provide a direct link to the relevant source file.
  • The semconv schema documentation should be more concise and prominently placed in the documentation hierarchy (both in JSON and Markdown formats).
  • Improve accessibility of the Weaver YAML schema documentation by providing a more prominent and direct link.
  • The filter parameter is confusing for first-time users. It would be useful to document:
    • The default behavior when no filter is applied.
    • Simple filtering examples.
    • Explanation of the ctx variable and how it interacts with filtering.</issue_description>

<agent_instructions>Check this issue for whether or not is up to date in accuracy, set your TODO list to include things that could be improved and issue a PR with those fixes.

Follow your other agent instructions.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Custom agent used: docs_agent
Expert technical writer for weaver


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 6 commits January 21, 2026 16:29
Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
…nctions

Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
…rce links

Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Copilot AI changed the title [WIP] Update Weaver documentation for improved clarity docs: Improve discoverability of Jinja resources, filters, and schema references Jan 21, 2026
Copilot AI requested a review from jsuereth January 21, 2026 16:38
@jsuereth
Copy link
Copy Markdown
Contributor

@copilot Can you update all your markdown links to be relative?

… file

Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Jan 21, 2026

@copilot Can you update all your markdown links to be relative?

Updated all markdown links to relative paths in commit b3c6742. Changes include:

  • docs/codegen.md: Converted all /crates/weaver_forge/... links to ../crates/weaver_forge/... and GitHub URLs to relative paths
  • README.md: Changed /crates/weaver_forge/README.md to ./crates/weaver_forge/README.md
  • crates/weaver_forge/README.md: Converted GitHub source links to relative ./src/extensions/... paths

Also removed DOCUMENTATION_IMPROVEMENTS_SUMMARY.md as requested.

Comment thread README.md Outdated
Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Copilot AI requested a review from jsuereth January 21, 2026 20:32
Comment thread crates/weaver_forge/README.md Outdated
Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
Copilot AI requested a review from jsuereth January 22, 2026 13:31
Comment thread docs/codegen.md
Comment thread docs/codegen.md Outdated
…er transition

Co-authored-by: jsuereth <29006+jsuereth@users.noreply.github.com>
@jsuereth jsuereth marked this pull request as ready for review January 22, 2026 13:37
@jsuereth jsuereth requested a review from a team as a code owner January 22, 2026 13:37
@codecov
Copy link
Copy Markdown

codecov Bot commented Jan 22, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.1%. Comparing base (b55473e) to head (db7fe27).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##            main   #1149     +/-   ##
=======================================
- Coverage   80.1%   80.1%   -0.1%     
=======================================
  Files        108     108             
  Lines       8440    8428     -12     
=======================================
- Hits        6763    6752     -11     
+ Misses      1677    1676      -1     

☔ 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.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread docs/codegen.md
@jsuereth jsuereth merged commit a74480e into main Jan 23, 2026
35 checks passed
@jsuereth jsuereth deleted the copilot/improve-documentation-clarity branch January 23, 2026 21:13
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.

Documentation Improvements

3 participants