semantica/docs/contributing.md

Contributing to Semantica

Thank you for your interest in contributing to Semantica! This guide provides detailed information about contributing to the project.

Quick Links

• Contributing Guide - Main contributing guide
• Code of Conduct - Community standards
• Security Policy - Security reporting
• GitHub Discussions - Community discussions

Documentation-Specific Guidelines

Writing Documentation

When contributing documentation, please follow these guidelines:

Style Guide

• Use clear, concise language
• Write for a technical audience but explain complex concepts
• Include code examples where helpful
• Use proper markdown formatting
• Follow the existing documentation structure

Code Examples

• Always include working code examples
• Test examples before submitting
• Use realistic scenarios
• Include expected output when relevant
• Add comments for clarity

API Documentation

When documenting APIs:

• Include function/class signatures with type hints
• Document all parameters and return values
• Provide usage examples
• Note any exceptions that may be raised
• Include performance considerations if relevant

Example:

def extract_entities(
    text: str,
    model: str = "transformer",
    confidence_threshold: float = 0.7
) -> List[Entity]:
    """Extract named entities from text.
    
    Args:
        text: Input text to process
        model: NER model to use (default: "transformer")
        confidence_threshold: Minimum confidence score (default: 0.7)
    
    Returns:
        List of extracted Entity objects
    
    Raises:
        ValueError: If text is empty or model is invalid
    
    Example:
        >>> from semantica.semantic_extract import NamedEntityRecognizer
        >>> ner = NamedEntityRecognizer()
        >>> entities = ner.extract("Apple Inc. was founded in 1976.")
        >>> len(entities)
        2
    """

Documentation Structure

The documentation is organized as follows:

docs/
├── index.md              # Homepage
├── getting-started.md    # Getting started guide
├── concepts.md          # Core concepts
├── modules.md           # Module overview
├── use-cases.md         # Use case examples
├── examples.md          # Code examples
├── learning-more.md     # Additional resources
├── cookbook/            # Interactive tutorials
│   ├── introduction/   # Beginner tutorials
│   ├── advanced/        # Advanced tutorials
│   └── use_cases/       # Domain-specific examples
└── reference/           # API reference
    ├── core.md
    ├── ingest.md
    └── ...

Adding New Documentation

1. Choose the right location:

   • Concepts → concepts.md
   • Tutorials → cookbook/
   • API docs → reference/
   • Examples → examples.md or cookbook/

2. Follow naming conventions:

   • Use lowercase with hyphens: my-new-doc.md
   • Be descriptive but concise

3. Update navigation:

   • Add to mkdocs.yml in the appropriate section

4. Add to index if needed:

   • Update docs/index.md if it's a major new section

Code Review Process

Documentation PRs go through the same review process as code:

1. Automated checks:

   • Markdown linting
   • Link checking
   • Build verification

2. Manual review:

   • Accuracy and clarity
   • Code example correctness
   • Consistency with existing docs

3. Feedback:

   • Reviewers provide constructive feedback
   • Address all comments before merging

Example Contributions

Fixing Typos

# Before
Semantica is a knowlege graph framework.

# After
Semantica is a knowledge graph framework.

Improving Clarity

# Before
The function does entity extraction.

# After
The function extracts named entities (people, organizations, locations, etc.) from text using advanced NLP models.

Adding Examples

## Example

Here's how to extract entities from text:

```python
from semantica.semantic_extract import NamedEntityRecognizer

ner = NamedEntityRecognizer()
entities = ner.extract("Apple Inc. was founded by Steve Jobs.")
print(f"Found {len(entities)} entities")

### Translation

We welcome translations of the documentation! If you'd like to translate:

1. Create a new directory: `docs/i18n/<language>/`
2. Translate the markdown files
3. Update `mkdocs.yml` to include the new language
4. Maintain the same structure as the English version

### Documentation Tools

We use:

- **MkDocs**: Documentation generator
- **Material for MkDocs**: Theme
- **mkdocstrings**: API documentation from docstrings
- **Mermaid**: Diagrams

### Getting Help

If you need help with documentation:

- Ask in [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
- Check existing documentation for examples
- Review other contributors' PRs

Thank you for helping improve Semantica's documentation! 📚