minecraft-datapack-language 17.0.10__py3-none-any.whl → 17.0.12__py3-none-any.whl

minecraft_datapack_language/_embedded/docs/_docs/contributing.md

@@ -0,0 +1,352 @@
+---
+layout: page
+title: Contributing
+permalink: /docs/contributing/
+---
+
+# Contributing to MDL
+
+Thank you for your interest in contributing to Minecraft Datapack Language (MDL)! This guide will help you get started.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9 or higher
+- Git
+- Basic knowledge of Python and Minecraft datapacks
+
+### Development Setup
+
+1. **Fork the repository**:
+   ```bash
+   git clone https://github.com/aaron777collins/MinecraftDatapackLanguage.git
+   cd MinecraftDatapackLanguage
+   ```
+
+2. **Install in development mode**:
+   ```bash
+   python -m pip install -e .
+   ```
+
+3. **Install development dependencies**:
+   ```bash
+   pip install -r requirements-dev.txt  # if available
+   ```
+
+4. **Verify installation**:
+   ```bash
+   mdl --version
+   mdl --help
+   ```
+
+## Project Structure
+
+```
+MinecraftDatapackLanguage/
+├── minecraft_datapack_language/    # Main package
+│   ├── __init__.py
+│   ├── cli.py                      # Command-line interface
+│   ├── mdl_parser_js.py            # JavaScript-style MDL parser
+│   ├── pack.py                     # Pack generation
+│   └── utils.py                    # Utility functions
+├── vscode-extension/               # VS Code extension
+├── scripts/                        # Build and release scripts
+├── tools/                          # Development tools
+├── docs/                           # Documentation
+└── tests/                          # Test files
+```
+
+## Areas to Contribute
+
+### 1. Core Language Features
+
+- **Parser improvements**: Enhance the MDL parser
+- **New syntax features**: Add new language constructs
+- **Error handling**: Improve error messages and validation
+- **Performance**: Optimize parsing and compilation
+
+### 2. CLI Tools
+
+- **New commands**: Add useful CLI commands
+- **Better output**: Improve user experience
+- **Configuration**: Add configuration options
+- **Integration**: Better integration with other tools
+
+### 3. Python Bindings
+
+- **Bindings improvements**: Enhance the Python bindings
+- **New features**: Add new capabilities
+- **Documentation**: Improve API documentation
+- **Examples**: Add more examples
+
+### 4. VS Code Extension
+
+- **Syntax highlighting**: Improve language support
+- **IntelliSense**: Add auto-completion
+- **Debugging**: Add debugging support
+- **Snippets**: Add code snippets
+
+### 5. Documentation
+
+- **User guides**: Improve existing documentation
+- **Examples**: Add more examples
+- **Tutorials**: Create step-by-step tutorials
+- **API docs**: Improve API documentation
+
+### 6. Testing
+
+- **Unit tests**: Add comprehensive tests
+- **Integration tests**: Test end-to-end functionality
+- **Performance tests**: Ensure good performance
+- **Regression tests**: Prevent bugs from returning
+
+## Development Workflow
+
+### 1. Choose an Issue
+
+1. Check the [Issues](https://github.com/aaron777collins/MinecraftDatapackLanguage/issues) page
+2. Look for issues labeled `good first issue` for beginners
+3. Comment on the issue to let others know you're working on it
+4. Fork the repository if you haven't already
+
+### 2. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 3. Make Changes
+
+- Write your code following the coding standards
+- Add tests for new functionality
+- Update documentation as needed
+- Test your changes thoroughly
+
+### 4. Test Your Changes
+
+```bash
+# Run the test suite
+python -m pytest
+
+# Test the CLI
+mdl --help
+mdl build --mdl sample.mdl -o test_output
+
+# Test the Python bindings
+python -c "from minecraft_datapack_language import Pack; print('API works!')"
+```
+
+### 5. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: add new feature description"
+```
+
+Use conventional commit messages:
+- `feat:` for new features
+- `fix:` for bug fixes
+- `docs:` for documentation changes
+- `test:` for test changes
+- `refactor:` for code refactoring
+
+### 6. Push and Create a Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a pull request on GitHub with:
+- Clear description of changes
+- Reference to related issues
+- Screenshots if applicable
+- Test results
+
+## Coding Standards
+
+### Python Code
+
+- **Style**: Follow PEP 8
+- **Type hints**: Use type hints where appropriate
+- **Docstrings**: Add docstrings to functions and classes
+- **Comments**: Add comments for complex logic
+
+### MDL Language
+
+- **Consistency**: Follow existing language patterns
+- **Error messages**: Provide clear, helpful error messages
+- **Performance**: Consider performance implications
+- **Backward compatibility**: Maintain compatibility when possible
+
+### Documentation
+
+- **Clarity**: Write clear, concise documentation
+- **Examples**: Include practical examples
+- **Structure**: Use consistent formatting
+- **Links**: Link to related documentation
+
+## Testing Guidelines
+
+### Unit Tests
+
+- **Coverage**: Aim for high test coverage
+- **Isolation**: Tests should be independent
+- **Naming**: Use descriptive test names
+- **Assertions**: Use specific assertions
+
+### Integration Tests
+
+- **End-to-end**: Test complete workflows
+- **Real scenarios**: Test realistic use cases
+- **Error cases**: Test error conditions
+- **Performance**: Test performance characteristics
+
+### Example Test
+
+```python
+def test_pack_creation():
+    """Test basic pack creation functionality."""
+    pack = Pack(name="Test Pack", pack_format=48)
+    
+    # Test namespace creation
+    namespace = pack.namespace("test")
+    assert namespace is not None
+    
+    # Test function addition
+    namespace.function("hello", 'say Hello!')
+    
+    # Test build
+    pack.build("test_output")
+    
+    # Verify output files exist
+    assert os.path.exists("test_output/test_pack/pack.mcmeta")
+    assert os.path.exists("test_output/test_pack/data/test/functions/hello.mcfunction")
+```
+
+## Documentation Guidelines
+
+### Writing Documentation
+
+- **Audience**: Write for the target audience
+- **Structure**: Use clear headings and sections
+- **Examples**: Include working examples
+- **Links**: Link to related topics
+
+### Code Examples
+
+- **Complete**: Provide complete, runnable examples
+- **Clear**: Use clear, descriptive variable names
+- **Commented**: Add comments explaining key parts
+- **Tested**: Ensure examples work correctly
+
+### API Documentation
+
+- **Parameters**: Document all parameters
+- **Return values**: Document return values
+- **Exceptions**: Document exceptions that may be raised
+- **Examples**: Include usage examples
+
+## Release Process
+
+### Version Management
+
+MDL uses semantic versioning:
+- **Major**: Breaking changes
+- **Minor**: New features (backward compatible)
+- **Patch**: Bug fixes (backward compatible)
+
+### Release Steps
+
+1. **Update version**: Update version in `pyproject.toml`
+2. **Update changelog**: Document changes in `CHANGELOG.md`
+3. **Test thoroughly**: Run all tests
+4. **Create release**: Use GitHub releases
+5. **Publish to PyPI**: Upload to Python Package Index
+
+### Release Scripts
+
+Use the provided release scripts:
+
+```bash
+# Create a patch release
+./scripts/release.sh patch "Bug fixes"
+
+# Create a minor release
+./scripts/release.sh minor "New features"
+
+# Create a major release
+./scripts/release.sh major "Breaking changes"
+```
+
+## Community Guidelines
+
+### Code of Conduct
+
+- **Respect**: Be respectful to all contributors
+- **Inclusive**: Welcome contributors from all backgrounds
+- **Constructive**: Provide constructive feedback
+- **Helpful**: Help others learn and grow
+
+### Communication
+
+- **Issues**: Use GitHub issues for bug reports and feature requests
+- **Discussions**: Use GitHub Discussions for questions and ideas
+- **Pull requests**: Provide clear, constructive feedback
+- **Documentation**: Help improve documentation
+
+### Recognition
+
+- **Contributors**: All contributors are recognized in the project
+- **Credits**: Credit contributors in release notes
+- **Thanks**: Thank contributors for their work
+
+## Getting Help
+
+### Questions and Support
+
+- **GitHub Issues**: For bug reports and feature requests
+- **GitHub Discussions**: For questions and general discussion
+- **Documentation**: Check the documentation first
+- **Examples**: Look at existing examples
+
+### Mentorship
+
+- **New contributors**: Experienced contributors can help newcomers
+- **Code reviews**: Get feedback on your code
+- **Pair programming**: Work together on features
+- **Documentation**: Help improve documentation
+
+## Future Roadmap
+
+### Planned Features
+
+- **Enhanced syntax**: More language features
+- **Better tooling**: Improved development tools
+- **Performance**: Better performance
+- **Integration**: Better integration with other tools
+
+### Contributing to the Roadmap
+
+- **Suggestions**: Suggest new features
+- **Prioritization**: Help prioritize features
+- **Implementation**: Implement planned features
+- **Testing**: Test new features
+
+## Legal
+
+### License
+
+MDL is licensed under the GPL-3.0 License. By contributing, you agree to license your contributions under the same license.
+
+### Copyright
+
+Contributors retain copyright to their contributions, but grant the project a license to use and distribute them.
+
+## Thank You
+
+Thank you for contributing to MDL! Your contributions help make the project better for everyone in the Minecraft community.
+
+Whether you're fixing a bug, adding a feature, improving documentation, or just asking questions, your involvement is valuable and appreciated.

minecraft_datapack_language/_embedded/docs/_docs/docs-hub.md

@@ -0,0 +1,266 @@
+---
+layout: page
+title: Documentation Hub
+permalink: /docs/docs-hub/
+description: Search and browse all MDL documentation
+---
+
+Search and browse all available documentation for the Minecraft Datapack Language (MDL).
+
+<div class="search-container">
+  <input type="text" id="docSearch" placeholder="Search documentation..." class="search-input">
+  <div class="search-icon">
+    <svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
+      <path fill-rule="evenodd" d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z" clip-rule="evenodd"/>
+    </svg>
+  </div>
+</div>
+
+<div class="docs-grid" id="docsGrid">
+  <div class="doc-card" data-categories="getting-started beginner">
+    <h3>🚀 Getting Started</h3>
+    <p>Learn the basics of MDL and set up your development environment.</p>
+    <div class="doc-meta">
+      <span class="category">Beginner</span>
+      <span class="category">Setup</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/getting-started/" class="doc-link">Get Started →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="language reference syntax">
+    <h3>📚 Language Reference</h3>
+    <p>Complete syntax reference, data types, functions, and language features.</p>
+    <div class="doc-meta">
+      <span class="category">Reference</span>
+      <span class="category">Syntax</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/language-reference/" class="doc-link">View Reference →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="cli command-line tools">
+    <h3>🔧 CLI Reference</h3>
+    <p>Command-line interface for building, testing, and managing MDL projects.</p>
+    <div class="doc-meta">
+      <span class="category">Tools</span>
+      <span class="category">CLI</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/cli-reference/" class="doc-link">CLI Guide →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="multi-file projects structure">
+    <h3>📁 Multi-file Projects</h3>
+    <p>Learn how to organize and structure larger, more complex MDL projects.</p>
+    <div class="doc-meta">
+      <span class="category">Advanced</span>
+      <span class="category">Structure</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/multi-file-projects/" class="doc-link">Project Structure →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="python bindings programming">
+    <h3>🐍 Python Bindings</h3>
+    <p>Programmatic access to MDL for automation and integration.</p>
+    <div class="doc-meta">
+      <span class="category">Bindings</span>
+      <span class="category">Python</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/python-bindings/" class="doc-link">Bindings Guide →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="vscode extension ide">
+    <h3>💻 VS Code Extension</h3>
+    <p>Enhanced development experience with syntax highlighting and IntelliSense.</p>
+    <div class="doc-meta">
+      <span class="category">IDE</span>
+      <span class="category">VS Code</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/vscode-extension/" class="doc-link">Extension Guide →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="examples code samples">
+    <h3>🎯 Examples</h3>
+    <p>Complete working examples to learn from and use as templates.</p>
+    <div class="doc-meta">
+      <span class="category">Examples</span>
+      <span class="category">Code</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/examples/" class="doc-link">View Examples →</a>
+  </div>
+  
+  <div class="doc-card" data-categories="contributing development">
+    <h3>🤝 Contributing</h3>
+    <p>How to contribute to the MDL project and development guidelines.</p>
+    <div class="doc-meta">
+      <span class="category">Community</span>
+      <span class="category">Development</span>
+    </div>
+    <a href="{{ site.baseurl }}/docs/contributing/" class="doc-link">Contribute →</a>
+  </div>
+</div>
+
+<div class="no-results" id="noResults" style="display: none;">
+  <h3>No documentation found</h3>
+  <p>Try searching with different keywords or browse all documentation above.</p>
+</div>
+
+<style>
+.search-container {
+  position: relative;
+  margin: 2rem 0;
+  max-width: 600px;
+}
+
+.search-input {
+  width: 100%;
+  padding: 1rem 3rem 1rem 1rem;
+  border: 2px solid #e1e4e8;
+  border-radius: 8px;
+  font-size: 1rem;
+  transition: border-color 0.2s, box-shadow 0.2s;
+}
+
+.search-input:focus {
+  outline: none;
+  border-color: #0366d6;
+  box-shadow: 0 0 0 3px rgba(3, 102, 214, 0.1);
+}
+
+.search-icon {
+  position: absolute;
+  right: 1rem;
+  top: 50%;
+  transform: translateY(-50%);
+  color: #586069;
+}
+
+.docs-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.doc-card {
+  background: #ffffff;
+  border: 1px solid #e1e4e8;
+  border-radius: 8px;
+  padding: 1.5rem;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.doc-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(0,0,0,0.2);
+}
+
+.doc-card.hidden {
+  display: none;
+}
+
+.doc-card h3 {
+  margin: 0 0 0.5rem 0;
+  color: #24292e;
+  font-size: 1.1rem;
+}
+
+.doc-card p {
+  margin: 0 0 1rem 0;
+  color: #586069;
+  line-height: 1.5;
+}
+
+.doc-meta {
+  margin-bottom: 1rem;
+}
+
+.category {
+  display: inline-block;
+  background: #f1f3f4;
+  color: #586069;
+  padding: 0.25rem 0.5rem;
+  border-radius: 4px;
+  font-size: 0.8rem;
+  margin-right: 0.5rem;
+  margin-bottom: 0.25rem;
+}
+
+.doc-link {
+  display: inline-block;
+  color: #0366d6;
+  text-decoration: none;
+  font-weight: 500;
+  padding: 0.5rem 1rem;
+  border: 1px solid #0366d6;
+  border-radius: 6px;
+  transition: background-color 0.2s, color 0.2s;
+}
+
+.doc-link:hover {
+  background: #0366d6;
+  color: #ffffff;
+  text-decoration: none;
+}
+
+.no-results {
+  text-align: center;
+  padding: 3rem;
+  color: #586069;
+}
+
+.no-results h3 {
+  margin-bottom: 0.5rem;
+  color: #24292e;
+}
+
+@media (max-width: 768px) {
+  .docs-grid {
+    grid-template-columns: 1fr;
+  }
+  
+  .search-input {
+    font-size: 16px; /* Prevents zoom on iOS */
+  }
+}
+</style>
+
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+  const searchInput = document.getElementById('docSearch');
+  const docsGrid = document.getElementById('docsGrid');
+  const docCards = docsGrid.querySelectorAll('.doc-card');
+  const noResults = document.getElementById('noResults');
+  
+  searchInput.addEventListener('input', function() {
+    const searchTerm = this.value.toLowerCase().trim();
+    let visibleCount = 0;
+    
+    docCards.forEach(card => {
+      const title = card.querySelector('h3').textContent.toLowerCase();
+      const description = card.querySelector('p').textContent.toLowerCase();
+      const categories = card.dataset.categories.toLowerCase();
+      
+      const matches = title.includes(searchTerm) || 
+                     description.includes(searchTerm) || 
+                     categories.includes(searchTerm);
+      
+      if (matches || searchTerm === '') {
+        card.classList.remove('hidden');
+        visibleCount++;
+      } else {
+        card.classList.add('hidden');
+      }
+    });
+    
+    // Show/hide no results message
+    if (visibleCount === 0 && searchTerm !== '') {
+      noResults.style.display = 'block';
+    } else {
+      noResults.style.display = 'none';
+    }
+  });
+  
+  // Focus search input on page load
+  searchInput.focus();
+});
+</script>