📝 feat(docs): add comprehensive documentation(#12)

Co-authored-by: oasaph <contato@asaph.dev>

Author: oasaph

.github/instructions/INSTRUCTIONS_CODE.md

@@ -0,0 +1,63 @@
+# Coding Instructions for LLM Tools
+
+## Purpose
+Guidelines for LLMs (e.g., GitHub Copilot) to generate, edit, and review code in the Flaggle project.
+
+## Coding Standards
+- Follow [PEP 8](https://peps.python.org/pep-0008/) for style.
+- Use type annotations for all public functions and methods.
+- Use Google-style docstrings for all public classes and methods.
+- Prefer explicit, readable code over cleverness.
+- Use triple double quotes (`"""`) for docstrings.
+- Add examples in docstrings for public APIs.
+- Use `from ... import ...` for imports within the package.
+
+## Docstring Directives
+- **Short docstring**: Use for simple, self-explanatory functions or classes. One concise sentence, no blank line after the summary.
+- **Long docstring**: Use for public, complex, or reusable code. Structure:
+  - First line: short summary.
+  - Blank line.
+  - Extended description (optional).
+  - Args: List all parameters, their types, and descriptions.
+  - Returns: Describe the return type and meaning.
+  - Raises: List exceptions that may be raised.
+  - Attributes: For classes, document all public attributes.
+  - Examples: (Optional) Add usage examples for clarity, using indented code blocks in docstrings and fenced code blocks (```python) in markdown/README.
+- **Tone**: Use clear, concise, and neutral language.
+- **Formatting**: Use triple double quotes (`"""`) and follow [PEP 257](https://peps.python.org/pep-0257/).
+- **Compatibility**: This template is compatible with VS Code, PyCharm, Sphinx, and most Python docstring tools. Structure is inspired by Google and NumPy conventions.
+
+## File Structure
+- Place new features in the appropriate module under `python_flaggle/`.
+- Place all tests in `tests/`.
+
+## Testing
+- All new code must be covered by tests.
+- Use `pytest` for all tests.
+- Strive for 100% code coverage.
+- Test both typical and edge cases.
+
+## Example Docstring
+```python
+class MyClass:
+    """
+    Short summary of the class.
+
+    Attributes:
+        attr1 (type): Description.
+    """
+    def my_method(self, param1: int) -> bool:
+        """
+        Short summary of the method.
+
+        Args:
+            param1 (int): Description.
+        Returns:
+            bool: Description.
+        Example:
+            ```python
+            obj = MyClass()
+            obj.my_method(1)
+            ```
+        """
+```

.github/instructions/INSTRUCTIONS_COMMITS.md

@@ -0,0 +1,19 @@
+# Commit Message Instructions for LLM Tools
+
+## Purpose
+Guidelines for LLMs to generate clear, conventional commit messages for the Flaggle project.
+
+## Format
+- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+  - `type(scope): subject`
+  - Example: `feat(flag): add support for float flag types`
+- Types: feat, fix, docs, style, refactor, test, chore
+- Use imperative mood (e.g., "add", not "adds")
+- Limit subject line to 72 characters
+- Use body to explain what and why, not how (if needed)
+- Reference issues or PRs if relevant
+
+## Examples
+- `fix(flaggle): handle ValueError in _fetch_flags`
+- `docs(readme): clarify JSON schema for flags endpoint`
+- `test(flag): add test for else branch in is_enabled`

.github/instructions/INSTRUCTIONS_DOCS.md

@@ -0,0 +1,30 @@
+# Documentation Instructions for LLM Tools
+
+## Purpose
+Guidelines for LLMs to generate and update documentation in the Flaggle project.
+
+## General Principles
+- All public APIs must be documented in `README.md` and/or module docstrings.
+- Use Markdown fenced code blocks (```python) for examples.
+- Use clear, concise, and neutral language.
+- Document the JSON schema for the flags endpoint.
+- Update the Table of Contents if new sections are added.
+
+## README.md Structure
+- Overview
+- Features
+- Installation
+- Getting Started
+- Flaggle Class: Configuration & Usage
+- Supported Operations
+- Advanced Usage: The Flag Class
+- JSON Schema for Flags Endpoint
+- Contributing
+- License
+- TODO / Roadmap
+
+## Best Practices
+- Use headings and subheadings for clarity.
+- Add usage examples for all major features.
+- Keep documentation up to date with code changes.
+- Add a changelog entry for significant documentation updates.

.github/instructions/INSTRUCTIONS_PR_BODY.md

@@ -0,0 +1,43 @@
+# Pull Request Body Instructions for LLM Tools
+
+## Purpose
+Guidelines for LLMs to generate clear, informative PR bodies for the Flaggle project.
+
+## Structure
+- **Summary**: Briefly describe what the PR does.
+- **Motivation**: Why is this change needed?
+- **Changes**: List major changes (new features, bug fixes, refactors, docs, tests).
+- **Testing**: Describe how the change was tested.
+- **Checklist**:
+  - [ ] Code follows style and docstring guidelines
+  - [ ] Tests added/updated and passing
+  - [ ] Documentation updated
+  - [ ] No unrelated changes
+- **Related Issues/PRs**: Reference any related issues or pull requests.
+
+## Example
+```
+## Summary
+Add async support to Flaggle's flag fetching.
+
+## Motivation
+Async support allows non-blocking flag updates in async applications.
+
+## Changes
+- Add async versions of fetch/update methods
+- Update tests for async
+- Update README with async usage
+
+## Testing
+- Added new async tests
+- All tests pass locally
+
+## Checklist
+- [x] Code follows style and docstring guidelines
+- [x] Tests added/updated and passing
+- [x] Documentation updated
+- [x] No unrelated changes
+
+## Related Issues/PRs
+Closes #42
+```

.vscode/settings.json

@@ -3,5 +3,19 @@
         "tests"
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    "python.testing.pytestEnabled": true,
+    "github.copilot.chat.codeGeneration.enabled": true,
+    "github.copilot.chat.codeGeneration.instructions": [
+        {
+            "file": ".github/instructions/INSTRUCTIONS_CODE.md",
+        },
+        {
+            "file": ".github/instructions/INSTRUCTIONS_DOCS.md",
+        }
+    ],
+    "github.copilot.chat.commitMessageGeneration.instructions": [
+        {
+            "file": ".github/instructions/INSTRUCTIONS_COMMITS.md",
+        }
+    ],
 }

README.md

@@ -238,6 +238,6 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 - [ ] **Async Support:** Add async/await support for non-blocking flag fetching and updates.
 - [ ] **Type Annotations & Validation:** Improve type safety and validation for flag values and operations.
 - [ ] **Better Error Handling & Logging:** More granular error reporting and logging options.
-- [ ] **Extensive Documentation & Examples:** Expand documentation with more real-world usage patterns and advanced scenarios.
+- [x] **Extensive Documentation & Examples:** Expand documentation with more real-world usage patterns and advanced scenarios.
 
 Contributions and suggestions are welcome! Please open an issue or pull request if you have ideas for improvements.

python_flaggle/__init__.py

@@ -1,3 +1,14 @@
+"""Flaggle: Python feature flag management library.
+
+This package provides the Flaggle class for managing feature flags, as well as the Flag, FlagType, and FlagOperation classes for defining and evaluating individual flags.
+
+Exports:
+    Flaggle: Main entry point for feature flag management.
+    Flag: Represents a single feature flag.
+    FlagType: Enum of supported flag value types.
+    FlagOperation: Enum of supported flag operations.
+"""
+
 from python_flaggle.flaggle import Flaggle
 from python_flaggle.flag import Flag, FlagOperation, FlagType