[GOOD FIRST ISSUE] Add Docstrings to DataSet Class Core Methods

[raphael-intugle]

---

name: Good First Issue
about: A beginner-friendly task perfect for first-time contributors
title: '[GOOD FIRST ISSUE] Add Docstrings to DataSet Class Core Methods'
labels: 'good first issue, documentation, enhancement'
assignees: ''

Welcome! 👋

This is a beginner-friendly issue perfect for first-time contributors to the Intugle project. We've designed this task to help you get familiar with our codebase while making a meaningful contribution.

Task Description

Add comprehensive docstrings to core methods in the DataSet class located in src/intugle/analysis/models.py. The methods load(), to_df(), and _repr_html_() currently lack proper documentation.

Why This Matters

Good docstrings:

• Help Developers: New contributors can understand what methods do without reading implementation
• Improve IDE Support: IDEs show docstrings as tooltips during development
• Reduce Onboarding Time: Makes it easier for new team members to understand the codebase

What You'll Learn

• Writing effective Python docstrings following Google or NumPy style
• Documenting class methods with parameters, return values, and examples
• Understanding the DataSet class architecture
• Best practices for technical documentation

Step-by-Step Guide

Prerequisites

• Python 3.10+ installed
• Git basics (clone, commit, push, pull request)
• Read our CONTRIBUTING.md guide

Setup Instructions

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/data-tools.git
   cd data-tools

2. Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -e ".[dev]"

4. Create a new branch

   git checkout -b docs/add-docstrings-dataset-core-methods

Implementation Steps

1. Open the file src/intugle/analysis/models.py

2. Add a docstring to the load() method (line 121):

   • Describe what the method does (loads dataset using the adapter)
   • Document any exceptions that might be raised
   • Explain when this method is called (hint: it's called in __init__)

3. Add a docstring to the to_df() method (line 360):

   • Describe what it returns (converts dataset to pandas DataFrame)
   • Document the return type
   • Add a simple usage example

4. Add a docstring to the _repr_html_() method (line 413):

   • Explain that this enables Jupyter notebook display
   • Describe what HTML is returned
   • Mention that this is automatically called by Jupyter

Files to Modify

• File: src/intugle/analysis/models.py
  • Change: Add comprehensive docstrings to load(), to_df(), and _repr_html_() methods
  • Line(s): 121 (load), 360 (to_df), 413 (repr_html)

Testing Your Changes

1. Verify docstrings render correctly:

   # In Python or IPython
   from intugle.analysis.models import DataSet
   help(DataSet.load)
   help(DataSet.to_df)
   help(DataSet._repr_html_)

2. Check linting:

   ruff check src/intugle/analysis/models.py

Submitting Your Work

Please run the following command to automatically fix linting issues before committing: ruff check --fix .

1. Commit your changes

   git add src/intugle/analysis/models.py
   git commit -m "Add docstrings to DataSet core methods (load, to_df, _repr_html_)"

2. Push to your fork

   git push origin docs/add-docstrings-dataset-core-methods

3. Create a Pull Request

   • Go to the original repository
   • Click "Pull Requests" → "New Pull Request"
   • Select your branch
   • Fill out the PR template
   • Reference this issue with "Fixes #ISSUE_NUMBER"

Expected Outcome

The three methods should have clear, comprehensive docstrings that explain:

• What the method does
• Parameters (if any)
• Return values
• Any exceptions raised
• Usage examples where helpful

Definition of Done

• Docstring added to load() method
• Docstring added to to_df() method
• Docstring added to _repr_html_() method
• Docstrings follow Google or NumPy style
• Docstrings render correctly with help() function
• No linter warnings
• Pull request submitted

Resources

• Project Documentation
• CONTRIBUTING.md

Need Help?

Don't hesitate to ask questions! We're here to help you succeed.

• Comment below with your questions
• Join our Discord for real-time support
• Tag maintainers: @raphael-intugle (if specific help needed)

Skills You'll Use

• Python basics
• Git and GitHub
• Technical writing
• Understanding class methods and their purpose

---

Thank you for contributing to Intugle!

Tips for Success:

• Read the method implementation to understand what it does
• Look at existing docstrings in the same file for style reference
• Keep docstrings clear and concise
• Include examples for user-facing methods
• Have fun! 🎉

[SIUUU42]

Hi! I would love to work on this issue as it seems like a good start for me to test my skills

[raphael-intugle]

Go ahead @SIUUU42 !