Merge pull request #263 from SylphAI-Inc/li_doc_github

[contributing guide]

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: 👍 Upvote an issue
+    url: https://github.com/SylphAI-Inc/AdalFlow/issues
+    about: You should upvote an issue if it is important to you.
   - name: 💬 Chat with us
     url: https://discord.gg/ezzszrRZvT
     about: Live chat with experts, engineers, and users in our Discord community.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+## What does this PR do?
+
+<!--
+Please include a summary of the change and which issue is fixed.
+Please also include relevant motivation and context.
+List any dependencies that are required for this change.
+
+If we didn't discuss your PR in Github issues there's a high chance it will not be merged.
+
+The following links the related issue to the PR (https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+-->
+
+Fixes #\<issue_number>
+
+<!-- Does your PR introduce any breaking changes? If yes, please list them. -->
+
+<details>
+  <summary><b>Before submitting</b></summary>
+
+- Was this **discussed/agreed** via a GitHub issue? (not for typos and docs)
+- [ ] Did you read the [contributor guideline](https://adalflow.sylph.ai/contributor/index.html)?
+- [ ] Did you make sure your **PR does only one thing**, instead of bundling different changes together?
+- Did you make sure to **update the documentation** with your changes? (if necessary)
+- Did you write any **new necessary tests**? (not for typos and docs)
+- [ ] Did you verify new and **existing tests pass** locally with your changes?
+- Did you list all the **breaking changes** introduced by this pull request?
+
+
+</details>
+
+
+<!--
+
+Did you have fun?
+
+Make sure you had fun coding 🙃
+
+-->

README.md

@@ -76,7 +76,20 @@ For AI researchers, product teams, and software engineers who want to learn the
 
 
 
+# Quick Start
+
+
+Install AdalFlow with pip:
 
+```bash
+pip install adalflow
+```
+
+Please refer to the [full installation guide](https://adalflow.sylph.ai/get_started/installation.html) for more details.
+
+
+* Try the [Building Quickstart](https://colab.research.google.com/drive/1TKw_JHE42Z_AWo8UuRYZCO2iuMgyslTZ?usp=sharing) in Colab to see how AdalFlow can build the task pipeline, including Chatbot, RAG, agent, and structured output.
+* Try the [Optimization Quickstart](https://colab.research.google.com/github/SylphAI-Inc/AdalFlow/blob/main/notebooks/qas/adalflow_object_count_auto_optimization.ipynb) to see how AdalFlow can optimize the task pipeline.
 
 
 # Why AdalFlow
@@ -194,21 +207,8 @@ Just define it as a ``Parameter`` and pass it to AdalFlow's ``Generator``.
 
 </p>
 
-# Quick Start
 
 
-Install AdalFlow with pip:
-
-```bash
-pip install adalflow
-```
-
-Please refer to the [full installation guide](https://adalflow.sylph.ai/get_started/installation.html) for more details.
-
-
-* Try the [Building Quickstart](https://colab.research.google.com/drive/1TKw_JHE42Z_AWo8UuRYZCO2iuMgyslTZ?usp=sharing) in Colab to see how AdalFlow can build the task pipeline, including Chatbot, RAG, agent, and structured output.
-* Try the [Optimization Quickstart](https://colab.research.google.com/github/SylphAI-Inc/AdalFlow/blob/main/notebooks/qas/adalflow_object_count_auto_optimization.ipynb) to see how AdalFlow can optimize the task pipeline.
-
 
 
 # Documentation
@@ -230,6 +230,13 @@ AdalFlow full documentation available at [adalflow.sylph.ai](https://adalflow.sy
 
 AdalFlow is named in honor of [Ada Lovelace](https://en.wikipedia.org/wiki/Ada_Lovelace), the pioneering female mathematician who first recognized that machines could go beyond mere calculations. As a team led by a female founder, we aim to inspire more women to pursue careers in AI.
 
+# Community & Contributors
+
+The AdalFlow is a community-driven project, and we welcome everyone to join us in building the future of LLM applications.
+
+Join our [Discord](https://discord.gg/ezzszrRZvT) community to ask questions, share your projects, and get updates on AdalFlow.
+
+To contribute, please read our [Contributor Guide](https://adalflow.sylph.ai/contributor/index.html).
 
 # Contributors
 

docs/README.md

@@ -22,12 +22,13 @@ AdalFlow uses [Sphinx](https://www.sphinx-doc.org/en/master/) and [reStructuredT
 AdalFlow documentation uses `poetry` and `pyproject.toml` to manage the dependencies. You can install all the necessary packages by running:
 
 ```
-
-poetry lock
+poetry lock --no-update
 poetry install
 ```
 
-**NOTE:** The default versions of `sphinx-build` and `poetry` that come with Linux may be out of date for AdalFlow's documentation. Using "pip install" will get the latest versions of those tools.
+**NOTE:** The default versions of `sphinx-build` and `poetry` that come with Linux may be out of date for AdalFlow's documentation. Using "pip install" will get the latest versions of those packages.
+
+
 
 <!--
 All the packages are manged in the project's ``pyproject.toml`` file in the doc dependencies section. You can install all the necessary packages by running:
@@ -99,12 +100,13 @@ For example, in the `index.rst`, the `:caption: Get Started` corresponds to the
 
 Existing sections include:
 
-`get_started/`: Includes installation and AdalFlow in 10 minutes
+* `get_started/`: Includes installation and AdalFlow in 10 minutes
 
-`tutorials/`: Includes our main tutorials
-`use_cases/`: Includes the use cases of AdalFlow that will be added in the future and which accepts community contributions
+* `tutorials/`: Includes our main tutorials
 
-`apis/`: All the source-code-related documents will be included in this directory
+* `use_cases/`: Includes the use cases of AdalFlow that will be added in the future and which accepts community contributions
+
+* `apis/`: All the source-code-related documents will be included in this directory
 
 <!-- `resources/`: Include all the AdalFlow-relevant resources. -->
 
@@ -175,31 +177,15 @@ make html
 
 And you will be able to find the newly added use_cases module.
 
-### Add New Docs
-
-If you want to add any written files such as README.md to the documentation, there is an easy way to transform the files to `.rst` files using `Pandoc`.
-
-- First, install Pandoc with Homebrew:
-
-    `brew install pandoc`
 
-- Then run `pandoc -s <input .md file> -o <path/to/target_rst_file>`. For example, in the root directory run `pandoc -s README.md -o docs/source/get_started/introduction.rst`.This command will take content from `README.md` and create an `introduction.rst` file in the specified directory.
-
-After editing, run
-
-```python
-cd docs
-make clean
-make html
-```
 
 ### Commit the Edited Documentation
 
 Remember to exclude any unnecessary files in `.gitignore`. Please don’t commit files in `docs/build`. We can dynamically build local documentation with the make files and `source/`.
 
 Please push your updates to the GitHub repo.
 
-The structure of the code base and the docs:
+The structure of the docs directory looks like this:
 
 ```
 AdalFlow/
@@ -227,12 +213,25 @@ AdalFlow/
 │   ├── conf.py
 │   ├── index.rst
 │   ├── Makefile
-├── core/
-│   ├── __init__.py
-│   ├── module1.py
-│   ├── module2.py
-├── components/
-│   ├── __init__.py
-│   ├── module1.py
-│   ├── module2.py
+│   ├── pyproject.toml
+│   ├── poetry.lock
+```
+
+
+## [Optional] Convert Markdown to reStructuredText
+
+If you want to add any written files such as README.md to the documentation, there is an easy way to transform the files to `.rst` files using `Pandoc`.
+
+- First, install Pandoc with Homebrew:
+
+    `brew install pandoc`
+
+- Then run `pandoc -s <input .md file> -o <path/to/target_rst_file>`. For example, in the root directory run `pandoc -s README.md -o docs/source/get_started/introduction.rst`.This command will take content from `README.md` and create an `introduction.rst` file in the specified directory.
+
+After editing, run
+
+```python
+cd docs
+make clean
+make html
 ```

docs/source/apis/index.rst

@@ -1,3 +1,5 @@
+.. _apis:
+
 API Reference
 =============
 

docs/source/contributor/contribute_to_code.rst

@@ -1,23 +1,58 @@
-Coding and Testing
+Development Essentials
 ======================================
-This document will cover how you can contribute to lightRAG codebase.
+This document will cover how you can set up the AdalFlow codebase and start coding, testing, and documentation.
 
 Set Up
 ^^^^^^^^^^^^^^^^^^^
-The current ``LightRAG`` code contribution supports `poetry <https://python-poetry.org/>`_ setup only. The team is working on optimizing the library and will get back to support more environment soon.
-If you are only interested in using ``LightRAG`` as a package, please check our `installation guide <https://lightrag.sylph.ai/get_started/installation.html#install-lightrag>`_.
+We mainly use `poetry <https://python-poetry.org/>`_ for dependency management and virtual environment setup.
+
+.. If you are only interested in using ``LightRAG`` as a package, please check our `installation guide <https://lightrag.sylph.ai/get_started/installation.html#install-lightrag>`_.
 
 To set up ``poetry`` and contribute, please check the following steps:
 
 1. **Clone the Repository:**
 
    .. code-block:: bash
 
-        git clone https://github.com/SylphAI-Inc/LightRAG
-        cd LightRAG
+        git clone https://github.com/SylphAI-Inc/AdalFlow
+        cd AdalFlow
+
+2. **Set Up the AdalFlow Dev Environment:**
+   The AdalFlow source code, tests, and dependencies are in the ``./adalflow`` directory.
+   The ``./adalflow/pyproject.toml`` controls the dependencies for the ``adalflow`` package.
+   Use Poetry to install the dependencies and set up the virtual environment:
+
+   .. code-block:: bash
+
+        cd adalflow
+        poetry install
+        poetry shell
+
+   Test the setup by running the tests at the ``./adalflow`` directory:
+
+   .. code-block:: bash
+
+        pytest tests
+
+3. **Set Up the Root Dev Environment:**
+   At the root directory, we have a ``pyproject.toml`` file that controls the dependencies for the root directory.
+
+   .. code-block:: bash
+
+        poetry install
+        poetry shell
+
+   This will install all relevant dependencies and the files in /use_cases, /tutorials, and /benchmarks will be using the development version of the ``adalflow`` package.
+   You should see output similar to the following:
+
+   .. code-block:: bash
+
+        - Installing adalflow (0.2.5 /Users/liyin/Documents/test/AdalFlow/adalflow)
+
 
-2. **Configure API Keys:**
 
+
+4. **[Optional] Configure API Keys in the Root Directory:**
    Copy the example environment file and add your API keys:
 
    .. code-block:: bash
@@ -31,64 +66,74 @@ To set up ``poetry`` and contribute, please check the following steps:
         # COHERE_API_KEY=YOUR_API_KEY_IF_YOU_USE_COHERE
         # HF_TOKEN=YOUR_API_KEY_IF_YOU_USE_HF
 
-3. **Install Dependencies:**
-
-    The ``./lightrag/pyproject.toml`` controls the dependencies for the ``LightRAG`` package.
-    Use Poetry to install the dependencies and set up the virtual environment:
+   This will be helpful for you to run tutorials, use cases, and benchmarks.
 
-   .. code-block:: bash
-        cd lightrag
-        poetry install
-        poetry shell
 
-Codebase Structure
+Coding
 ^^^^^^^^^^^^^^^^^^^
-It is recommended to check our `LightRAG codebase structure <https://lightrag.sylph.ai/developer_notes/index.html>`_ and current `API references <https://lightrag.sylph.ai/apis/index.html>`_ to familiarize yourself with the directories and paths before contributing.
+Structuring
+~~~~~~~~~~~~~~~
+It is recommended to check our the structuring in :ref:`part1-structuring` and :doc:`../apis/index`
+to understand the codebase structure.
 
-Code Examples
-^^^^^^^^^^^^^^^^^^^
-We want to support you with our best. We have included code samples in the `tutorial <https://lightrag.sylph.ai/developer_notes/index.html>`_ for you to refer to.
+What to code
+~~~~~~~~~~~~~~~
+Please check the :ref:`part3-contributing-steps` to see some coding examples and steps to contribute to the codebase.
 
-We inlcude a list of potential samples(`We are working in progress to add more`):
+Code Tips
+~~~~~~~~~~~~~~~
+* Please follow the `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_.
 
-- `ModelClient integration <https://lightrag.sylph.ai/developer_notes/model_client.html#model-inference-sdks>`_. This document will help if you want to add new models not included in our codebase.
-- `Retriever Integration <https://lightrag.sylph.ai/developer_notes/retriever.html#retriever-in-action>`_. We provide different retrivers but you can create more.
+* Functions and classes should include standard docstrings and comments. Please refer to `documentation contribution guidelines <./contribute_to_document.html>`_ for standard docstrings.
 
-Code Tips
-^^^^^^^^^^^^^^^^^^^
-* When writing code, it is appreciated to include any important docstrings and comments. Please refer to `documentation contribution guidelines <./contribute_to_document.html>`_ for standard docstrings.
-* LightRAG is a Python library and if you could follow the `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_, the codebase will be more consistent.
+Copilot
+~~~~~~~~~~~~~~~
+We suggest you use `GitHub Copilot <https://copilot.github.com/>`_ to help you write code faster and more efficiently.
+You can follow this `Guide <https://docs.github.com/en/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot>`_ to set it up with your IDE.
+There are other options like `Cursor <https://www.cursor.com/>`_ and `Tabnine <https://www.tabnine.com/>`_ that you can use as well.
 
 Dependencies
-^^^^^^^^^^^^^^^^^^^
-If you want to add any new dependencies to the package, please include them in your PR description to inform us.
-Since we have already set up the testing automatic workflow in GitHub, please also set your new dependencies in
-``./lightrag/pyproject.toml`` file ``[tool.poetry.group.test.dependencies]`` section to avoid dependency errors in our CI/CD workflow.
-
-In order to correctly add the dependency using ``poetry``, please run
+~~~~~~~~~~~~~~~
+1. If you want to add any new dependencies to the package, please include them in your PR description to inform us.
+2. Since we have already set up the testing automatic workflow in GitHub, please also set your new dependencies in ``./adalflow/pyproject.toml`` file ``[tool.poetry.group.test.dependencies]`` section to avoid dependency errors in our CI/CD workflow.
+   In order to correctly add the dependency using ``poetry``, please run
 
-.. code-block:: bash
+   .. code-block:: bash
 
-        poetry add --group test <package-name>
+      poetry add --group test <package-name>
 
 Testing
 ^^^^^^^^^^^^^^^^^^^
 After you update the code, please make sure your code is well tested before making a pull request.
-There is a ``./lightrag/tests`` folder in the project directory to host your unit testing cases.
+There is a ``./adalflow/tests`` folder in the project directory to host your unit testing cases.
 
 You might need to install the testing packages using ``poetry``:
 
 For example:
 
 .. code-block:: bash
 
-        poetry add --group test unittest
-        poetry add --group test pytest
-        poetry add --group test mypy
+        poetry install # or
+        poetry add --group test
+
+
+You should name your test files with the following format: ``test_<module_name>.py``.
+
+Activate the virtual environment from `./adalflow` and run the tests:
 
+.. code-block:: bash
+
+    poetry shell
+    pytest
 
-All the test scripts should start with ``test_``. For example, run the individual test for ``components`` with:
+To run a specific test file, you can use the following command:
 
 .. code-block:: bash
 
-    python lightrag/tests/test_components.py
+    pytest tests/test_components.py
+
+For more details on testing, please refer to the `README.md <https://github.com/SylphAI-Inc/AdalFlow/blob/main/adalflow/tests/README.md>`_ under the ``./adalflow/tests`` directory.
+
+Documentation
+^^^^^^^^^^^^^^^^^^^
+Please refer to the `README.md <https://github.com/SylphAI-Inc/AdalFlow/blob/main/docs/README.md>`_ under the ``./docs`` directory for more details on how to contribute to the documentation.