Merge pull request #15 from sachahu1/dev

feat: documentation and extras

CHANGELOG.md

@@ -1,6 +1,18 @@
 # CHANGELOG
 
 
+## v0.3.0-rc.1 (2024-11-26)
+
+### Features
+
+- Improve installation instructions and update project info
+  ([`a47b410`](https://github.com/sachahu1/Github-Search-Engine/commit/a47b410a0694e0617af1360bc865880e4f6f2f57))
+
+- Added detailed installation steps for PyPI, source, and manual methods - Updated project
+  information in documentation - Enhanced API server launch instructions - Refactored code for
+  better readability and maintainability
+
+
 ## v0.2.3 (2024-11-26)
 
 

README.md

@@ -8,17 +8,42 @@
 
 ## Getting Started
 
-To get started simply install the package:
+### Installation
+
+#### Installing the package (from PyPI)
+You can install this package from PyPI using:
+```shell
+pip install Github-Search-Engine[cpu]
+```
+You can also choose to install extras:
+```shell
+pip install Github-Search-Engine[gpu,api]
+```
+
+#### Installing the package (from source)
+You can install this package from source using:
 ```shell
 pip install git+https://github.com/sachahu1/Github-Search-Engine.git
 ```
-You can then start using the tool with the CLI:
+
+#### Installing the package (Manual)
+You can also install the package yourself by cloning the repo:
 ```shell
-github_search_engine
+git clone https://github.com/sachahu1/Github-Search-Engine.git
+```
+
+And installing the package with poetry:
+```shell
+poetry install
 ```
 
 ### Using as a CLI tool
-You can use this package as a CLI tool, to do that, start by indexing your favourite GitHub repository:
+You can use this package as a CLI tool, start with:
+```shell
+github_search_engine -h
+```
+
+Once you're more familiar with the CLI, you can index your favourite GitHub repository:
 ```shell
 github_search_engine index <owner> <repository_name> --db_path=./local-store --github_access_token=<Your GitHub Personal Access Token>
 ```

docs/source/conf.py

@@ -22,11 +22,11 @@
 # -- Project information -----------------------------------------------------
 
 project = "Github-Search-Engine"
-copyright = "{% now 'utc', '%Y' %}, "
+copyright = "2024, Sacha Hu"
 author = "Sacha hu"
 
 # The full version, including alpha/beta/rc tags
-release = "0.2.3"
+release = "0.3.0-rc.1"
 
 source_suffix = {
   ".rst": "restructuredtext",

docs/source/custom/pre-modules/introduction.md

@@ -1,30 +1,83 @@
-# Introduction
+# Github-Search-Engine
 
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/sachahu1/Github-Search-Engine/run-tests.yaml?branch=main&label=Tests)
 
-## Installation
-### Installing Poetry
-This tool uses poetry. If you already have poetry installed,
-please skip to the next section. Otherwise, let's first setup poetry.
+![GitHub Release](https://img.shields.io/github/v/release/sachahu1/Github-Search-Engine)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/github_search_engine)
+![GitHub Repo stars](https://img.shields.io/github/stars/sachahu1/Github-Search-Engine)
 
-To install poetry, simply run this command:
+## Getting Started
+
+### Installation
+
+#### Installing the package (from PyPI)
+You can install this package from PyPI using:
+```shell
+pip install Github-Search-Engine[cpu]
+```
+You can also choose to install extras:
 ```shell
-curl -sSL https://install.python-poetry.org | python3 -
+pip install Github-Search-Engine[gpu,api]
 ```
-You can find out more about poetry installation [here](https://python-poetry.org/docs/master/#installation).
 
-That's it, poetry is set up.
+#### Installing the package (from source)
+You can install this package from source using:
+```shell
+pip install git+https://github.com/sachahu1/Github-Search-Engine.git
+```
 
-### Installing the package
-Thanks to poetry, installing this package is very simple and can be done in a single command. Simply run:
+#### Installing the package (Manual)
+You can also install the package yourself by cloning the repo:
+```shell
+git clone https://github.com/sachahu1/Github-Search-Engine.git
+```
+
+And installing the package with poetry:
 ```shell
 poetry install
 ```
-That's it, the package is installed. Move to the next section to learn how to use this package.
 
-## Getting Started
-< Add instructions on how to use project here >
+### Using as a CLI tool
+You can use this package as a CLI tool, start with:
+```shell
+github_search_engine -h
+```
+
+Once you're more familiar with the CLI, you can index your favourite GitHub repository:
+```shell
+github_search_engine index <owner> <repository_name> --db_path=./local-store --github_access_token=<Your GitHub Personal Access Token>
+```
+Then, search through any issue using:
+```shell
+github_search_engine search <owner> <repository_name> "<Your query>" --db_path=./local-store --github_access_token=<Your GitHub Personal Access Token>
+```
+
+### Launching an API server
+You can use this package as an API. To do that, simply run:
+```shell
+github_search_engine api --github_access_token=<Your GitHub Personal Access Token>
+```
+
 ## Building the documentation
-To build the documentation you can simply use the docker image. To do so, simply run:
+### Using Docker
+To access the documentation locally, the easiest way is to use the docker image. To do so, simply run:
 ```shell
 docker build . -f Dockerfile --target documentation -t github_search_engine-docs
+docker run -p 80:80 -it github_search_engine-docs
+```
+Then navigate to [http://localhost](http://localhost)
+
+### Manually
+Alternatively you can build the documentation yourself.
+First, make sure you have the dependencies installed:
+```shell
+poetry install --with=documentation
+```
+Then build the documentation:
+```shell
+poetry run sphinx-build -M html docs/source/ docs/build
+```
+Then open the documentation in your browser:
+```shell
+open docs/build/html/index.html
 ```

github_search_engine/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.2.3"
+__version__ = "0.3.0-rc.1"
 
 from github_search_engine import _cli as _cli

github_search_engine/_api/api.py

@@ -1,14 +1,13 @@
 import os
 from contextlib import asynccontextmanager
-from typing import Optional
 
 from fastapi import FastAPI
 from pydantic import BaseModel
 
 from github_search_engine.github_search_engine import GithubSearchEngine
 
 
-search_engine: Optional[GithubSearchEngine] = None
+search_engine: GithubSearchEngine | None = None
 
 
 class Repository(BaseModel):

github_search_engine/cli.py

@@ -1,9 +1,19 @@
+"""The simplest way to use this tool is via the cli.
+
+To get started, run the CLI tool with:
+
+.. code-block:: bash
+
+  $ github-search-engine -h
+
+"""
+
 from cleo.application import Application
 
 from github_search_engine import _cli as cli
 
 
-def run():
+def _run():
   application = Application()
   application.add(cli.ApiCommand())
   application.add(cli.IndexCommand())

github_search_engine/clients/github_client_manager.py

@@ -1,5 +1,3 @@
-from typing import List
-
 from githubkit import GitHub
 from githubkit.versions.v2022_11_28.models import Issue
 from githubkit.versions.v2022_11_28.models import IssueComment
@@ -21,7 +19,7 @@ def __init__(self, access_token: str):
 
   async def get_repository_issues(
     self, owner: str, repository_name: str
-  ) -> List[Issue]:
+  ) -> list[Issue]:
     """Retrieve issues from a specified GitHub repository.
 
     This function connects to a given GitHub repository and retrieves a list of
@@ -51,7 +49,7 @@ async def get_repository_issues(
 
   def get_issue_comments(
     self, owner: str, repository_name: str, issue_number: int
-  ) -> List[IssueComment]:
+  ) -> list[IssueComment]:
     """Retrieve comments for a specific issue in a repository.
 
     Args:
@@ -73,7 +71,7 @@ def get_issue_references(
     owner: str,
     repository_name: str,
     issue_number: int,
-  ) -> List[TimelineCrossReferencedEvent]:
+  ) -> list[TimelineCrossReferencedEvent]:
     """Fetch mentions to a given issue.
 
     Fetches the timeline events for a specific issue and filters out the

github_search_engine/clients/ollama_client_manager.py

@@ -1,3 +1,5 @@
+from typing import Sequence
+
 import ollama
 from ollama import GenerateResponse
 from ollama import Options
@@ -9,7 +11,15 @@ def __init__(self):
     self._model = "llama3.1:8b"
     self._context_size = 128_000
 
-  def embed(self, content: str):
+  def embed(self, content: str) -> Sequence[Sequence[float]]:
+    """Returns the LLM's embedding for the given input text.
+
+    Args:
+      content: The input textual content to embed.
+
+    Returns:
+      The embedding vector for the corresponding segment of the input content.
+    """
     response = self.client.embed(
       model=self._model,
       input=content,
@@ -18,6 +28,14 @@ def embed(self, content: str):
     return response.embeddings
 
   def chat(self, prompt: str) -> str:
+    """Generates a response to the input prompt.
+
+    Args:
+        prompt: The input text to generate a response for.
+
+    Returns:
+        The generated response.
+    """
     response: GenerateResponse = self.client.generate(
       model=self._model,
       prompt=prompt,