🤝 How to Contribute
=================================================================================

.. raw:: html

   <div align="center">
   <p>
   <strong>🎉 Thank you for considering contributions to this project! 🎉</strong><br>
   We welcome new methods, enhancements, bug fixes, and improvements to the existing content.
   </p>
   </div>

.. note::
   📋 **Quick Start**: To ensure consistency and smooth integration, please follow the guidelines below.

1. ➕ Add or Update Methods
-----------------------------

Each method is stored as an **individual YAML file** in the ``methods/`` directory. This makes it easy to add new methods or edit existing ones without navigating through a large file.

🆕 **To add a new method:**
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. 📁 **Create File**: New YAML file in the ``methods/`` directory with a descriptive filename (e.g., ``my_new_method.yaml``)
2. 📝 **Follow Structure**: Use existing method files as templates, including these required fields:

   .. code-block:: yaml

      Method: Method Name                    # 🏷️ Official method name
      Year: 2024                            # 📅 Publication year
      Published: true                        # ✅ Publication status (true/false)

      Description: |                         # 📄 Detailed description
        A comprehensive description of the method, including its approach,
        key features, and how it works. This text appears in the 
        expandable table rows on the website.
      
      Task:                                  # 🎯 List of computational tasks
        - Task Category 1
        - Task Category 2
      
      Publication: https://doi.org/10.1000/example     # 📖 DOI or URL
      Code Availability: https://github.com/user/repo  # 💻 Repository link

   **Additional optional fields:**
   
   - ``Model``: List of underlying models or frameworks
   - ``Inspired by``: List of references or inspirations

✏️ **To edit an existing method:**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. 🔍 **Find File**: Locate the corresponding YAML file in the ``methods/`` directory
2. ✏️ **Edit Directly**: Modify the file - filenames correspond to method names (lowercased with special characters replaced)

.. tip::
   💡 **File Naming**: Use descriptive names based on the method name:
   
   - ``Method: cPCA`` → ``cpca.yaml``
   - ``Method: GEARS`` → ``gears.yaml``
   - ``Method: scGEN`` → ``scgen.yaml``

.. warning::
   ⚠️ **YAML Syntax**: Please ensure valid YAML syntax and follow existing entries for examples.

---

2. 🔄 Continuous Integration
-----------------------------

.. raw:: html

   <div class="highlight-success">
   <p><strong>🚀 Automated Workflow</strong></p>
   </div>

A **GitHub Actions workflow** automatically runs ``generate_methods.py`` against ``methods.rst.j2`` whenever your pull request is merged into ``main``. This regenerates ``source/methods.rst`` to reflect your changes.

.. important::
   ✅ **No Manual Work Required**: You do **NOT** need to run any commands manually for the table update!

---

3. 🔍 Local Preview (Optional)
--------------------------------

If you wish to preview the changes locally before pushing your PR:

.. code-block:: bash

   # 📦 Set up environment
   conda env create -f environment.yml
   
   # 🔄 Activate environment (once created)
   conda activate iep-singlecell
   
   # 🏗️ Generate docs and build
   python generate_methods.py && make -C docs clean html

📱 **View Results**: Open ``docs/build/html/index.html`` in a browser.

---

4. 🛡️ Quality Guidelines
---------------------------

.. raw:: html

   <div class="admonition tip">
   <p class="admonition-title">💡 Best Practices</p>

**For Method Descriptions:**

- 📝 Be **comprehensive but concise** - aim for 3-5 sentences
- 🎯 **Focus on the key innovation** or distinguishing features  
- 🔗 **Mention the main application** area or use case
- ⚙️ **Include technical details** that help users understand the approach

**For Code Availability:**

- ✅ Use ``'-'`` if no code is available
- 🔗 Prefer **GitHub/GitLab** links over personal websites
- 📦 Link to the **main repository**, not individual files

**For Publications:**

- 🏷️ Use **DOI links** when available (``https://doi.org/10.xxxx/...``)
- 📰 For preprints, use **bioRxiv/arXiv** links
- 📚 Ensure the link is **publicly accessible**

.. raw:: html

   </div>

---

5. 🆘 Getting Help
--------------------

.. raw:: html

   <div class="admonition question">
   <p class="admonition-title">❓ Need Assistance?</p>

- 💬 **Questions**: Open a GitHub issue with the ``question`` label
- 🐛 **Bug Reports**: Use the ``bug`` label and provide details  
- 💡 **Feature Requests**: Use the ``enhancement`` label
- 📧 **Direct Contact**: Reach out to the maintainers

.. raw:: html

   </div>

---

.. raw:: html

   <div align="center">
   <h3>🙏 <strong>Thank You for Contributing!</strong> 🙏</h3>
   <p><em>Every contribution helps make this resource better for the entire single-cell community.</em></p>
   <p>🌟 <strong>Don't forget to star the repository if you find it useful!</strong> 🌟</p>
   </div>