Skip to content

Comprehensive enhancements to component how-to#716

Open
dotsdl wants to merge 1 commit intodocs/component_howtofrom
component-howto-enhancements
Open

Comprehensive enhancements to component how-to#716
dotsdl wants to merge 1 commit intodocs/component_howtofrom
component-howto-enhancements

Conversation

@dotsdl
Copy link
Member

@dotsdl dotsdl commented Jan 23, 2026

This PR builds on @atravitz's component how-to (#667) by adding critical fixes and comprehensive enhancements.

🔴 Critical Fixes (Must Have)

These fix technical errors that would mislead users:

  1. Fixed method names: Changed to_dict()/from_dict() to _to_dict()/_from_dict() (with underscores) - the actual method names
  2. Added missing imports: First test example now includes all required imports (GufeTokenizableTestsMixin, pytest, Chem)
  3. Fixed Sphinx references: Corrected :ref: syntax for proper cross-linking
  4. Added serialization warning: Critical warning that custom attributes require implementing serialization methods
  5. Added news entry: news/component-howto.rst per project requirements

🟢 Enhancements (Nice to Have)

These bring the guide to the comprehensive quality level of protocol.rst:

  • Overview section (~28 lines): Explains Component characteristics and available base classes
  • When to Create Custom Components (~18 lines): 5 practical use cases
  • Enhanced Step 3 (~20 lines): Structured breakdown of required methods by inheritance scenario
  • Using your Component (~33 lines): Complete working example showing full workflow
  • Best practices and tips (~25 lines): 9 actionable recommendations
  • Common pitfalls (~10 lines): 5 specific mistakes to avoid

📊 Stats

  • Total additions: ~176 lines
  • Final length: 269 lines (vs 125 in base)
  • Structure: Matches docs/how-tos/protocol.rst quality

Integration Note

This PR incorporates your stylistic improvements from the latest commits:

  • ✅ "it merely creates a new class identical to..." (Step 4 intro)
  • ✅ "test all of your new features" (better phrasing)

Feel free to:

  • Merge all changes
  • Cherry-pick only the critical fixes
  • Suggest modifications to any section

All changes have been reviewed to ensure they align with the project's documentation style.


Note: I've also posted the 5 critical fixes as individual review comments on the main PR #667 for reference.

This PR builds on the original component how-to by adding:

## Critical Fixes
- Fix method names: _to_dict() and _from_dict() (not to_dict/from_dict)
- Add missing imports in test examples
- Fix Sphinx reference syntax
- Add serialization warning for custom attributes
- Add news entry

## Enhancements
- Add Overview section explaining Component characteristics
- Add 'When to Create Custom Components' with 5 use cases
- Enhance Step 3 with structured breakdown of required methods
- Add 'Using your Component' section with complete workflow example
- Add 'Best practices and tips' section (9 recommendations)
- Add 'Common pitfalls' section (5 specific issues)

This brings the component how-to to the same comprehensive quality level
as the protocol how-to (protocol.rst).

Total additions: ~145 lines
Matches structure of: docs/how-tos/protocol.rst

Co-authored-by: Alyssa Travitz <atravitz@users.noreply.github.com>
@github-actions
Copy link

No API break detected ✅

@codecov
Copy link

codecov bot commented Jan 23, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.79%. Comparing base (7aa3568) to head (776dfdc).

Additional details and impacted files
@@                  Coverage Diff                  @@
##           docs/component_howto     #716   +/-   ##
=====================================================
  Coverage                 98.79%   98.79%           
=====================================================
  Files                        40       40           
  Lines                      2492     2492           
=====================================================
  Hits                       2462     2462           
  Misses                       30       30           

☔ 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.

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.

1 participant