Data-Science-For-Beginners/translations/fa/AGENTS.md

AGENTS.md

نمای کلی پروژه

داده‌کاوی برای مبتدیان یک برنامه آموزشی جامع ۱۰ هفته‌ای و ۲۰ درس است که توسط مدافعان ابری Microsoft Azure ایجاد شده است. این مخزن یک منبع آموزشی است که مفاهیم پایه‌ای داده‌کاوی را از طریق درس‌های مبتنی بر پروژه، شامل دفترچه‌های Jupyter، آزمون‌های تعاملی و تکالیف عملی آموزش می‌دهد.

فناوری‌های کلیدی:

• دفترچه‌های Jupyter: رسانه اصلی یادگیری با استفاده از Python 3
• کتابخانه‌های پایتون: pandas، numpy، matplotlib برای تحلیل داده‌ها و مصورسازی
• Vue.js 2: برنامه آزمون (پوشه quiz-app)
• Docsify: تولیدکننده سایت مستندات برای دسترسی آفلاین
• Node.js/npm: مدیریت بسته برای اجزای جاوااسکریپت
• Markdown: تمام محتوای درس‌ها و مستندات

معماری:

• مخزن آموزشی چندزبانه با ترجمه‌های گسترده
• ساختار یافته در ماژول‌های درس (۱-مقدمه تا ۶-داده‌کاوی در دنیای واقعی)
• هر درس شامل README، دفترچه‌ها، تکالیف و آزمون‌ها است
• برنامه آزمون مستقل Vue.js برای ارزیابی‌های قبل/بعد از درس
• پشتیبانی از GitHub Codespaces و کانتینرهای توسعه VS Code

دستورات راه‌اندازی

راه‌اندازی مخزن

# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners

راه‌اندازی محیط پایتون

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

راه‌اندازی برنامه آزمون

# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint

سرور مستندات Docsify

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

راه‌اندازی پروژه‌های مصورسازی

برای پروژه‌های مصورسازی مانند meaningful-visualizations (درس ۱۳):

# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint

جریان کاری توسعه

کار با دفترچه‌های Jupyter

1. Jupyter را در ریشه مخزن شروع کنید: jupyter notebook
2. به پوشه درس مورد نظر بروید
3. فایل‌های .ipynb را باز کنید تا تمرین‌ها را انجام دهید
4. دفترچه‌ها خودکفا هستند و شامل توضیحات و سلول‌های کد می‌باشند
5. بیشتر دفترچه‌ها از pandas، numpy و matplotlib استفاده می‌کنند - مطمئن شوید که این‌ها نصب شده‌اند

ساختار درس‌ها

هر درس معمولاً شامل موارد زیر است:

• README.md - محتوای اصلی درس با تئوری و مثال‌ها
• notebook.ipynb - تمرین‌های عملی دفترچه Jupyter
• assignment.ipynb یا assignment.md - تکالیف تمرینی
• پوشه solution/ - دفترچه‌ها و کدهای حل تمرین
• پوشه images/ - مواد بصری پشتیبان

توسعه برنامه آزمون

• برنامه Vue.js 2 با قابلیت بارگذاری مجدد در زمان توسعه
• آزمون‌ها در quiz-app/src/assets/translations/ ذخیره می‌شوند
• هر زبان پوشه ترجمه مخصوص به خود را دارد (en، fr، es و غیره)
• شماره‌گذاری آزمون‌ها از ۰ شروع شده و تا ۳۹ ادامه دارد (۴۰ آزمون در کل)

افزودن ترجمه‌ها

• ترجمه‌ها در پوشه translations/ در ریشه مخزن قرار می‌گیرند
• ساختار کامل درس‌ها از انگلیسی در هر زبان منعکس می‌شود
• ترجمه خودکار از طریق GitHub Actions (co-op-translator.yml)

دستورالعمل‌های تست

تست برنامه آزمون

cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve

تست دفترچه‌ها

• هیچ چارچوب تست خودکاری برای دفترچه‌ها وجود ندارد
• اعتبارسنجی دستی: تمام سلول‌ها را به ترتیب اجرا کنید تا مطمئن شوید خطایی وجود ندارد
• بررسی کنید که فایل‌های داده قابل دسترسی هستند و خروجی‌ها به درستی تولید می‌شوند
• مطمئن شوید که مصورسازی‌ها به درستی نمایش داده می‌شوند

تست مستندات

# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation

بررسی کیفیت کد

# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors

دستورالعمل‌های سبک کدنویسی

پایتون (دفترچه‌های Jupyter)

• از دستورالعمل‌های سبک PEP 8 برای کد پایتون پیروی کنید
• از نام‌های متغیر واضحی استفاده کنید که داده‌های تحلیل شده را توضیح دهند
• سلول‌های Markdown با توضیحات قبل از سلول‌های کد قرار دهید
• سلول‌های کد را بر روی مفاهیم یا عملیات‌های واحد متمرکز کنید
• از pandas برای دستکاری داده‌ها و matplotlib برای مصورسازی استفاده کنید
• الگوی وارد کردن معمول:

  import pandas as pd
  import numpy as np
  import matplotlib.pyplot as plt
  

جاوااسکریپت/Vue.js

• از دستورالعمل‌های سبک Vue.js 2 و بهترین شیوه‌ها پیروی کنید
• پیکربندی ESLint در quiz-app/package.json
• از اجزای تک‌فایلی Vue (.vue files) استفاده کنید
• معماری مبتنی بر اجزا را حفظ کنید
• قبل از ثبت تغییرات، npm run lint را اجرا کنید

مستندات Markdown

• از سلسله‌مراتب واضح عناوین (# ## ### و غیره) استفاده کنید
• بلوک‌های کد با مشخص‌کننده زبان اضافه کنید
• متن جایگزین برای تصاویر اضافه کنید
• به درس‌ها و منابع مرتبط لینک دهید
• طول خطوط را برای خوانایی مناسب نگه دارید

سازماندهی فایل‌ها

• محتوای درس‌ها در پوشه‌های شماره‌گذاری شده (01-defining-data-science و غیره)
• حل تمرین‌ها در زیرپوشه‌های اختصاصی solution/
• ترجمه‌ها ساختار انگلیسی را در پوشه translations/ منعکس می‌کنند
• فایل‌های داده در data/ یا پوشه‌های مخصوص درس نگهداری می‌شوند

ساخت و استقرار

استقرار برنامه آزمون

cd quiz-app

# Build production version
npm run build

# Output is in dist/ folder
# Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.)

استقرار برنامه‌های وب ایستا Azure

برنامه آزمون می‌تواند در Azure Static Web Apps مستقر شود:

1. ایجاد منبع Azure Static Web App
2. اتصال به مخزن GitHub
3. تنظیمات ساخت را پیکربندی کنید:
   • مکان برنامه: quiz-app
   • مکان خروجی: dist
4. جریان کاری GitHub Actions به صورت خودکار با هر push مستقر می‌شود

سایت مستندات

# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify

GitHub Codespaces

• مخزن شامل پیکربندی کانتینر توسعه است
• Codespaces به صورت خودکار محیط Python و Node.js را تنظیم می‌کند
• مخزن را از طریق رابط کاربری GitHub در Codespace باز کنید
• تمام وابستگی‌ها به صورت خودکار نصب می‌شوند

دستورالعمل‌های درخواست کشش (Pull Request)

قبل از ارسال

# For Vue.js changes in quiz-app
cd quiz-app
npm run lint
npm run build

# Test changes locally
npm run serve

قالب عنوان PR

• از عناوین واضح و توصیفی استفاده کنید
• قالب: [Component] توضیح مختصر
• مثال‌ها:
  • [Lesson 7] رفع خطای وارد کردن دفترچه پایتون
  • [Quiz App] افزودن ترجمه آلمانی
  • [Docs] به‌روزرسانی README با پیش‌نیازهای جدید

بررسی‌های مورد نیاز

• مطمئن شوید که تمام کد بدون خطا اجرا می‌شود
• دفترچه‌ها را به طور کامل اجرا کنید
• اطمینان حاصل کنید که برنامه‌های Vue.js به درستی ساخته می‌شوند
• بررسی کنید که لینک‌های مستندات کار می‌کنند
• برنامه آزمون را در صورت تغییر تست کنید
• مطمئن شوید که ترجمه‌ها ساختار سازگار را حفظ می‌کنند

دستورالعمل‌های مشارکت

• از سبک و الگوهای کدنویسی موجود پیروی کنید
• برای منطق پیچیده توضیحات اضافه کنید
• مستندات مرتبط را به‌روزرسانی کنید
• تغییرات را در ماژول‌های مختلف درس در صورت لزوم تست کنید
• فایل CONTRIBUTING.md را مرور کنید

یادداشت‌های اضافی

کتابخانه‌های رایج مورد استفاده

• pandas: دستکاری و تحلیل داده‌ها
• numpy: محاسبات عددی
• matplotlib: مصورسازی و نمودار داده‌ها
• seaborn: مصورسازی داده‌های آماری (برخی درس‌ها)
• scikit-learn: یادگیری ماشین (درس‌های پیشرفته)

کار با فایل‌های داده

• فایل‌های داده در پوشه data/ یا دایرکتوری‌های مخصوص درس قرار دارند
• بیشتر دفترچه‌ها فایل‌های داده را در مسیرهای نسبی انتظار دارند
• فایل‌های CSV فرمت اصلی داده هستند
• برخی درس‌ها از JSON برای مثال‌های داده غیررابطه‌ای استفاده می‌کنند

پشتیبانی چندزبانه

• بیش از ۴۰ ترجمه زبان از طریق GitHub Actions خودکار
• جریان کاری ترجمه در .github/workflows/co-op-translator.yml
• ترجمه‌ها در پوشه translations/ با کدهای زبان قرار دارند
• ترجمه‌های آزمون در quiz-app/src/assets/translations/

گزینه‌های محیط توسعه

1. توسعه محلی: نصب Python، Jupyter، Node.js به صورت محلی
2. GitHub Codespaces: محیط توسعه ابری فوری
3. کانتینرهای توسعه VS Code: توسعه مبتنی بر کانتینر محلی
4. Binder: اجرای دفترچه‌ها در ابر (در صورت پیکربندی)

دستورالعمل‌های محتوای درس

• هر درس مستقل است اما بر مفاهیم قبلی بنا می‌شود
• آزمون‌های قبل از درس دانش قبلی را ارزیابی می‌کنند
• آزمون‌های بعد از درس یادگیری را تقویت می‌کنند
• تکالیف تمرین عملی ارائه می‌دهند
• Sketchnotes خلاصه‌های بصری ارائه می‌دهند

رفع مشکلات رایج

مشکلات کرنل Jupyter:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

خطاهای نصب npm:

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

خطاهای وارد کردن در دفترچه‌ها:

• مطمئن شوید که تمام کتابخانه‌های مورد نیاز نصب شده‌اند
• سازگاری نسخه پایتون را بررسی کنید (پایتون ۳.۷+ توصیه می‌شود)
• مطمئن شوید که محیط مجازی فعال است

Docsify بارگذاری نمی‌شود:

• مطمئن شوید که از ریشه مخزن سرویس‌دهی می‌کنید
• بررسی کنید که index.html وجود دارد
• دسترسی شبکه مناسب را تضمین کنید (پورت ۳۰۰۰)

ملاحظات عملکرد

• مجموعه داده‌های بزرگ ممکن است زمان بارگذاری در دفترچه‌ها طول بکشد
• نمایش مصورسازی‌ها ممکن است برای نمودارهای پیچیده کند باشد
• سرور توسعه Vue.js امکان بارگذاری مجدد سریع را فراهم می‌کند
• ساخت‌های تولید بهینه‌سازی و کوچک‌سازی شده‌اند

یادداشت‌های امنیتی

• هیچ داده حساس یا اطلاعات کاربری نباید ثبت شود
• از متغیرهای محیطی برای هر کلید API در درس‌های ابری استفاده کنید
• درس‌های مرتبط با Azure ممکن است به اطلاعات حساب Azure نیاز داشته باشند
• وابستگی‌ها را برای وصله‌های امنیتی به‌روز نگه دارید

مشارکت در ترجمه‌ها

• ترجمه‌های خودکار از طریق GitHub Actions مدیریت می‌شوند
• اصلاحات دستی برای دقت ترجمه استقبال می‌شود
• ساختار پوشه ترجمه موجود را دنبال کنید
• لینک‌های آزمون را به پارامتر زبان اضافه کنید: ?loc=fr
• درس‌های ترجمه شده را برای نمایش صحیح تست کنید

منابع مرتبط

• برنامه اصلی: https://aka.ms/datascience-beginners
• Microsoft Learn: https://docs.microsoft.com/learn/
• مرکز دانش‌آموزی: https://docs.microsoft.com/learn/student-hub
• انجمن بحث: https://github.com/microsoft/Data-Science-For-Beginners/discussions
• سایر برنامه‌های آموزشی Microsoft: ML برای مبتدیان، AI برای مبتدیان، توسعه وب برای مبتدیان

نگهداری پروژه

• به‌روزرسانی‌های منظم برای حفظ محتوای به‌روز
• مشارکت‌های جامعه استقبال می‌شود
• مشکلات در GitHub پیگیری می‌شوند
• PRها توسط نگهدارندگان برنامه بررسی می‌شوند
• بررسی‌ها و به‌روزرسانی‌های ماهانه محتوا

---

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.