utopia-project 0.37.1 → 0.37.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6467795f4ec1c68ecc0606fbd6ca86367532a9f4ba85ecd7a45d9246037c289
-  data.tar.gz: 143589e65aa521ef0ccab3886a02ccd86cd6e83519b91935ad3a1bf14086e1cf
+  metadata.gz: ff8f37c4088abefc8d202fff07c8cb1f4e93db97b2404c76f72c4be6119d26b2
+  data.tar.gz: 49a84a3901624ab103390ccb86682fa1b7d0173bb2a538e7af11e298e3e9a0a6
 SHA512:
-  metadata.gz: 67297da20eb02586984c38b3586cf844600b67179b50d00a13f15e264399cd83fe79420d64348139eabf368fc0d56fd73fe730b7f42c19c4247032e3423cf261
-  data.tar.gz: c384960157c37c7a3934a40c2b557fbdf9b054a889104be3599beba0d8d9ec9143c0523c72ebd14f1d853c9394f82b318078f57c9394de4ae039eb148169e782
+  metadata.gz: ba907fede639f4d98bf395737a66cbedc0a2c494a2795d69d6750b96a86cc0472cc030981f2e7c074a7255612396ffddeda83baf0f26ee187d256adfe2d9a9ef
+  data.tar.gz: 746bb13682244238a91f27cdad40674713d63ee598528e6c1359d629029d4c6db8176fbe2263a5375e91d3bd320c5c84c62aa61a3851cd8f1f6fcd95a47022a5

data/bake/utopia/project.rb

@@ -3,6 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2020-2025, by Samuel Williams.
 
+def initialize(context)
+	super
+	
+	require "fileutils"
+end
+
 # Create an empty project in the current directory.
 def create
 	template_path = File.expand_path("../../template/*", __dir__)

data/context/documentation-guidelines.md

@@ -63,6 +63,92 @@ documentation-guides:
 
 Every guide should start with a brief overview, explaining its purpose and what the user can expect to learn: "This guide explains how to use x to do y." – it should be short and to the point, as it's used as the description of the guide on other pages that link to it.
 
+## Guide Writing Principles
+
+### Context Before Implementation
+
+Every feature or concept should be introduced with clear context about why users need it before explaining how to use it. This helps users understand when and why to apply the feature in their own projects.
+
+**Structure each section as:**
+1. **Problem statement**: What challenge does this solve?
+2. **Use cases**: When would users encounter this need?
+3. **Solution overview**: How does this feature address the problem?
+4. **Implementation**: Code examples and detailed usage
+
+**Example:**
+
+❌ **Poor context**:
+~~~markdown
+## Transactions
+
+Use MULTI and EXEC to run commands atomically:
+
+```ruby
+client.multi
+client.set("key", "value")
+client.exec
+```
+~~~
+
+✅ **Good context**:
+~~~markdown
+## Transactions
+
+When multiple clients modify the same data simultaneously, you need to prevent race conditions and ensure data consistency. Redis transactions solve this by executing multiple commands atomically - either all succeed or none do.
+
+Use transactions when you need:
+- **Data consistency**: Keep related fields synchronized
+- **Atomic updates**: Prevent partial updates that could corrupt data
+- **Race condition prevention**: Ensure operations complete without interference
+
+```ruby
+client.multi
+client.set("user:balance", new_balance)
+client.set("user:last_transaction", transaction_id)
+client.exec
+```
+~~~
+
+### Advanced Feature Documentation
+
+When documenting advanced features, follow this structure:
+
+1. **Motivation Section**: Start with 2-3 bullet points explaining:
+   - What problem this solves
+   - When users would need this
+   - What happens without this feature
+
+2. **Use Case Examples**: Provide concrete scenarios:
+   - Business logic examples (user accounts, inventory, etc.)
+   - Technical scenarios (performance, reliability, etc.)
+   - Anti-patterns to avoid
+
+3. **Implementation**: Show practical code examples
+4. **Best Practices**: When to use vs when not to use
+5. **Common Pitfalls**: What to watch out for
+
+**Template:**
+```markdown
+## [Feature Name]
+
+[Brief explanation of what problem this solves and why it matters]
+
+Use [feature] when you need:
+- **[Primary use case]**: [Brief explanation]
+- **[Secondary use case]**: [Brief explanation]
+- **[Third use case]**: [Brief explanation]
+
+[Implementation examples with practical scenarios]
+
+### Best Practices
+
+[When to use this feature vs alternatives]
+
+### Common Pitfalls
+
+[What to avoid and why]
+```
+
 #### "Getting Started" Guide
 
 Every project should have a "Getting Started" guide that provides an introduction to the project, including the following sections:
@@ -103,3 +189,107 @@ In the above example:
 
 - "Core Concepts" is optional and should be included if it helps to clarify the usage and structure of the project.
 - "Specific Scenario" only makes sense if there are more than one scenario that is typical.
+
+## Guide Organization
+
+### Learning Path Structure
+
+Organize guides to follow a natural learning progression:
+
+1. **Core Guides**: Essential concepts all users need
+   - Getting Started (installation, basic usage, core concepts)
+   - [Primary feature guides in order of typical adoption]
+
+2. **Operational Guides**: Specific use cases and patterns
+   - [Advanced features organized by user journey]
+
+3. **Architecture Guides**: System design and scaling decisions
+   - [When to use different approaches/clients/patterns]
+
+### Content Depth Guidelines
+
+- **Getting Started**: Cover 80% of what new users need to be productive
+- **Feature Guides**: Deep dive into specific capabilities with real-world context
+- **Architecture Guides**: Help users make informed decisions between alternatives
+
+Each guide should be self-contained but may reference other guides for deeper context.
+
+### User Journey Considerations
+
+Consider when in a user's journey they'll encounter each feature:
+
+- **Immediate need**: Basic operations, connection management.
+- **Growth stage**: Performance optimization, bulk operations.
+- **Scale stage**: Clustering, high availability, advanced patterns.
+
+Help users understand when to choose between alternatives:
+- Compare approaches side-by-side.
+- Explain trade-offs clearly.
+- Provide decision criteria.
+- Include performance implications.
+
+## Code Examples in Guides
+
+### Contextual Examples
+
+Every code example should demonstrate a realistic scenario, not abstract operations:
+
+❌ **Abstract**:
+```ruby
+client.set("key", "value")
+client.get("key")
+```
+
+✅ **Contextual**:
+```ruby
+# Store user session data:
+client.set("session:#{session_id}", user_data.to_json)
+client.expire("session:#{session_id}", 3600)
+
+# Retrieve session for authentication:
+session_data = client.get("session:#{session_id}")
+```
+
+### Comment Style
+
+- **Colon (`:`)**: When comment refers to the next line(s).
+- **Period (`.`)**: When comment describes what just happened.
+- **No trailing comments**: Avoid end-of-line comments.
+
+### Error Handling
+
+Include proper error handling and resource management in examples:
+- Always use `ensure` blocks for cleanup.
+- Show common error scenarios.
+- Demonstrate graceful degradation patterns.
+
+### Progressive Disclosure
+
+Start with simple examples, then show advanced usage:
+1. Basic usage that works immediately.
+2. Common configuration options.
+3. Advanced patterns and edge cases.
+4. Production considerations.
+
+## Enhanced Guide Quality Standards
+
+Following `utopia-project` guidelines, each guide should:
+
+1. **Start with clear purpose**: "This guide explains how to use X to solve Y problem"
+2. **Provide user context**: Explain why users would need this feature
+3. **Include practical examples**: Working code samples that demonstrate real scenarios
+4. **Follow consistent structure**: Problem → Use Cases → Implementation → Best Practices
+5. **Cross-reference appropriately**: Use `{ruby ClassName}` for internal references
+6. **Include error handling**: Show how to handle common failure scenarios
+7. **Provide troubleshooting**: Common issues and solutions
+8. **Maintain currency**: Keep examples updated with latest best practices
+
+### Section Checklist
+
+Before publishing a guide section, verify:
+- [ ] Explains WHY users need this feature.
+- [ ] Provides concrete use cases.
+- [ ] Shows realistic code examples.
+- [ ] Includes proper error handling.
+- [ ] Mentions when NOT to use the feature.
+- [ ] References related concepts appropriately.

data/lib/utopia/project/sidebar.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2025, by Samuel Williams.
 
 require_relative "renderer"
 
@@ -88,7 +88,7 @@ module Utopia
 			end
 			
 			private
-
+			
 			def self.extract_headings_from_document(document)
 				headings = []
 				return headings unless document&.root

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.37.1"
+		VERSION = "0.37.2"
 	end
 end

data/public/_static/site.css

@@ -237,6 +237,7 @@ h1, h2, h3, h4, h5, h6, p, pre, ul, dl, ol {
 div.mermaid {
 	margin: 1rem;
 	text-align: center;
+	color: initial; /* Don't inherit page text color */
 }
 
 div.giscus {

data/readme.md

@@ -31,6 +31,10 @@ Please see the [project documentation](https://socketry.github.io/utopia-project
 
 Please see the [project releases](https://socketry.github.io/utopia-project/releases/index) for all releases.
 
+### v0.37.2
+
+  - Fix mermaid diagram text color in dark mode.
+
 ### v0.36.0
 
   - Introduce `bake utopia:project:update` which invokes readme and agent context updates.

data/releases.md

@@ -1,5 +1,9 @@
 # Changes
 
+## v0.37.2
+
+  - Fix mermaid diagram text color in dark mode.
+
 ## v0.36.0
 
   - Introduce `bake utopia:project:update` which invokes readme and agent context updates.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.37.1
+  version: 0.37.2
 platform: ruby
 authors:
 - Samuel Williams
@@ -285,7 +285,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A project documentation tool based on Utopia.
 test_files: []