مستندات

• راهنمای محتوایی
• راهنماها و برگه تقلب RST

این راهنمای مقدماتی به شما کمک می‌کند ابزارها و دانش لازم برای مشارکت در مستندسازی را کسب کنید.

اگر با زبان reStructuredText آشنا نیستید، معرفی به زبان reStructuredText را مطالعه کنید. سپس، دو روش برای شروع مشارکت در مستندات وجود دارد:

• برای تغییرات جزئی، مانند افزودن یک پاراگراف یا اصلاح یک اشتباه تایپی، توصیه می‌کنیم از رابط کاربری GitHub استفاده کنید. این روش آسان‌ترین و سریع‌ترین راه برای ارسال تغییرات است و برای افراد غیر فنی مناسب می‌باشد. برای شروع، مستقیماً به بخش مشارکت در مستندسازی مراجعه کنید.

• برای تغییرات پیچیده‌تر، مانند افزودن یک صفحه جدید، لازم است که از Git استفاده کنید و با یک نسخه محلی از مستندات کار کنید. ابتدا دستورالعمل‌های بخش راه‌اندازی محیط را دنبال کنید تا محیط خود را آماده کنید.

همچنین ببینید

راه‌های دیگر برای مشارکت در Odoo را کشف کنید

متن بازسازی‌شده (RST)

مستندات به زبان reStructuredText (RST) نوشته شده است، یک زبان نشانه‌گذاری سبک که شامل متن معمولی همراه با نشانه‌گذاری است و امکان افزودن عناوین، تصاویر، یادداشت‌ها و موارد دیگر را فراهم می‌کند. RST استفاده آسانی دارد، حتی اگر با آن آشنا نباشید.

مهم

هنگام نوشتن مستندات، به محتوا و راهنمای RST توجه کنید. این کار تضمین می‌کند که مستندات یکپارچه باقی بمانند و فرآیند تأیید تغییرات توسط تیم Odoo را تسهیل می‌کند.

راه‌اندازی محیط

دستورالعمل‌های زیر به شما کمک می‌کنند محیط خود را برای اعمال تغییرات محلی در مستندات آماده کرده و سپس آنها را به GitHub ارسال کنید. اگر قبلاً این مرحله را تکمیل کرده‌اید یا می‌خواهید تغییرات را از طریق رابط کاربری GitHub انجام دهید، این بخش را رد کرده و به مشارکت در مستندسازی بروید.

1. ابتدا یک حساب کاربری در GitHub ایجاد کنید <https://github.com/join>. اودو از GitHub برای مدیریت کد منبع محصولات خود استفاده می‌کند و اینجا جایی است که تغییرات خود را ارسال خواهید کرد.

2. یک کلید SSH جدید ایجاد کنید و آن را در حساب GitHub خود ثبت کنید <https://docs.github.com/en/authentication/connecting-to-github-with-ssh>.

3. به github.com/odoo/documentation بروید و روی دکمه Fork در گوشه بالا سمت راست کلیک کنید تا یک فورک (نسخه شخصی شما) از مخزن در حساب کاربری‌تان ایجاد شود. این کار یک نسخه از کد اصلی ایجاد می‌کند که می‌توانید تغییرات خود را روی آن اعمال کنید بدون اینکه بر کد اصلی تأثیر بگذارد. اگر در Odoo کار می‌کنید، این مرحله را نادیده بگیرید.

4. گیت را نصب کنید. این یک ابزار خط فرمان (یک رابط متنی) است که امکان ردیابی تاریخچه تغییرات ایجاد شده در یک فایل و مهم‌تر از آن، کار بر روی نسخه‌های مختلف آن فایل به طور همزمان را فراهم می‌کند. این بدان معناست که هنگام ایجاد تغییرات، نیازی به نگرانی در مورد بازنویسی کار در حال انجام شخص دیگری ندارید.

   تأیید کنید که دایرکتوری نصب Git در متغیر PATH سیستم شما قرار دارد.

   Linux and macOSWindows

   راهنمای «به‌روزرسانی متغیر PATH در لینوکس و macOS <https://unix.stackexchange.com/a/26059>`_ را با مسیر نصب Git (به‌طور پیش‌فرض /usr/bin/git) دنبال کنید.

5. پیکربندی Git برای شناسایی شما به عنوان نویسنده‌ی مشارکت‌های آینده‌تان. همان آدرس ایمیلی را وارد کنید که برای ثبت‌نام در GitHub استفاده کرده‌اید.

   $ git config --global user.name "Your Name"
   $ git config --global user.email "youremail@example.com"
   

6. منابع را با Git کلون کنید و وارد مخزن محلی شوید.

   $ git clone git@github.com:odoo/documentation.git
   $ cd documentation
   

7. پیکربندی Git برای ارسال تغییرات به فورک شما به جای پایگاه کد اصلی. در دستورات زیر، <your_github_account> را با نام حساب GitHub که فورک را در آن ایجاد کرده‌اید جایگزین کنید. اگر در Odoo کار می‌کنید، این مرحله را نادیده بگیرید.

   $ git remote add dev git@github.com:<your_github_account>/documentation.git
   

8. پیکربندی گیت برای تسهیل همکاری بین نویسندگانی که از سیستم‌های مختلف می‌آیند.

   Linux and macOSWindows

   $ git config --global core.autocrlf input
   $ git config commit.template `pwd`/commit_template.txt
   

9. آخرین نسخه‌ی پایتون و پیپ را نصب کنید.

10. وابستگی‌های پایتون مستندات را با استفاده از pip نصب کنید.

    $ pip install -r requirements.txt
    

    تأیید کنید که دایرکتوری نصب وابستگی‌های پایتون در متغیر PATH سیستم شما گنجانده شده است.

    Linux and macOSWindows

    راهنمای «به‌روزرسانی متغیر PATH در لینوکس و macOS <https://unix.stackexchange.com/a/26059>`_» را با مسیر نصب وابستگی‌های پایتون دنبال کنید (به‌صورت پیش‌فرض ~/.local/bin).

11. نصب Make.

    LinuxmacOSWindows

    $ sudo apt install make -y
    

12. نصب pngquant.

13. اکنون آماده هستید تا اولین مشارکت خود را با Git انجام دهید.

مشارکت در مستندسازی

Contribute from the GitHub interfaceContribute with Git

1. ابتدا یک حساب کاربری در GitHub ایجاد کنید <https://github.com/join>. اودو از GitHub برای مدیریت کد منبع محصولات خود استفاده می‌کند و اینجا جایی است که تغییرات خود را ارسال خواهید کرد.

2. تأیید کنید که در حال مرور مستندات نسخه‌ای هستید که قصد تغییر آن را دارید. نسخه را می‌توان از منوی کشویی در بالای صفحه انتخاب کرد.

3. به صفحه‌ای که می‌خواهید تغییر دهید بروید و روی دکمه Edit on GitHub در گوشه بالا سمت راست صفحه کلیک کنید.

4. روی دکمه Fork this repository کلیک کنید تا یک فورک (نسخه‌ای مخصوص به خودتان) از مخزن در حساب کاربری‌تان ایجاد کنید. این کار یک کپی از کد منبع ایجاد می‌کند که می‌توانید تغییرات خود را در آن اعمال کنید بدون اینکه کد منبع اصلی تحت تأثیر قرار گیرد. اگر در Odoo کار می‌کنید، این مرحله را نادیده بگیرید.

   

5. تغییرات مورد نظر را با رعایت دستورالعمل‌های محتوا و RST اعمال کنید.

   نکته

   روی دکمه پیش‌نمایش تغییرات کلیک کنید تا مشارکت خود را در قالبی خواناتر بررسی کنید. توجه داشته باشید که پیش‌نمایش قادر به پردازش صحیح تمام نشانه‌گذاری‌ها نیست. به عنوان مثال، یادداشت‌ها و نکات به صورت متن ساده نمایش داده می‌شوند.

6. به پایین صفحه بروید و فرم کوچک را پر کنید تا تغییرات خود را پیشنهاد دهید. در اولین کادر متنی، خلاصه‌ای بسیار کوتاه از تغییرات خود بنویسید. برای مثال، "اصلاح یک اشتباه تایپی" یا "افزودن مستندات برای صدور فاکتور سفارش‌های فروش." در کادر متنی دوم توضیح دهید چرا این تغییرات را پیشنهاد می‌کنید. سپس روی دکمه پیشنهاد تغییرات کلیک کنید.

   

7. تغییرات خود را بررسی کنید و روی دکمه ایجاد درخواست ادغام کلیک کنید.

8. کادر اجازه ویرایش توسط نگهدارنده را علامت بزنید. اگر در Odoo کار می‌کنید، این مرحله را رد کنید.

9. خلاصه‌ای که درباره تغییرات خود نوشته‌اید را مرور کنید و دوباره روی دکمه ایجاد درخواست کشش کلیک کنید.

10. در پایین صفحه، وضعیت قابلیت ادغام را بررسی کنید و هرگونه مشکل را برطرف کنید.

11. به محض آماده شدن PR شما برای ادغام، یکی از اعضای تیم Odoo به‌طور خودکار برای بررسی اختصاص داده می‌شود. اگر بازبین سوال یا نظری داشته باشد، آن‌ها را به‌صورت نظرات ارسال می‌کند و شما از طریق ایمیل مطلع خواهید شد. این نظرات باید حل شوند تا مشارکت ادامه یابد.

12. پس از تأیید تغییرات شما، بازبین آنها را ادغام می‌کند و روز بعد به صورت آنلاین نمایش داده می‌شوند.