Skip to content

Commit 784a81e

Browse files
Jimmy-seraph1080Jimmy-seraph1080
authored
Merge pull request #13 from compsys-progtools/4-githelp-high-level
4 githelp high level
2 parents be56ae8 + 4f75b79 commit 784a81e

File tree

17 files changed

+1043
-1
lines changed

17 files changed

+1043
-1
lines changed

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
recursive-include src/githelp/data/overlays *.yml

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,11 @@
1-
# githelp
1+
# Welcome to GitHelp
2+
3+
Learn Git faster, directly from your terminal, with friendly tips and optional AI powered explanations.
4+
5+
## Description
6+
7+
Githelp is a command line tool designed to help CSC311 student understand and remember Git commands, while working through git. Instead of searching the web every time, you forget what `git status` or `git rebase` does, you can ask Githelp inside the terminal.
8+
9+
GitHelp reads from a set of tips which are stored in a YAML file and can also use an AI model (`llama2` one of Ollama model) to generate a more detail explanations when available. Whether you’re just starting with Git or brushing up on specific commands, GitHelp can help you on the fly.
10+
11+
With a focus on clarity, GitHelp aims to reduce frustration, support learning by doing, and make Git feel less intimidating.

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# API Reference
2+
3+
This page shows the Python API for GitHelp, generated from docstrings.
4+
5+
```{eval-rst}
6+
.. autofunction:: githelp.ollama.ask_ollama
7+
.. autofunction:: githelp.overlays.read_yaml
8+
.. autofunction:: githelp.overlays.load_overlay
9+
.. autofunction:: githelp.overlays.list_overlay_name
10+
.. autofunction:: githelp.overlays.render_overlay
11+
.. autofunction:: githelp.overlays.render_name
12+
.. autofunction:: githelp.cli.githelp_cli
13+
.. autofunction:: githelp.cli.list_cmd
14+
.. autofunction:: githelp.cli.explain_cmd
15+
.. autofunction:: githelp.cli.tips_cmd

‎docs/cli.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# CLI
2+
3+
GitHelp is used from the terminal with the `githelp` command.
4+
This page shows all available commands, options, and arguments.
5+
6+
For each command, the gray box shows the usage line.
7+
8+
These follow common bash / Unix conventions:
9+
- the `[]` do not get used, they indicate that there might be more than one item in that position
10+
- `[OPTIONS]` refers to any optional inputs or options
11+
- `[ARGS]` refers to required inputs, or arguments
12+
13+
examples of what usage lines mean:
14+
- `githelp --help` or `githelp -h`
15+
Run `githelp` with the `--help` or `-h` option to see help.
16+
17+
- `githelp`
18+
Run `githelp` with no subcommand. This will show the help text and the GitHelp menu (including available tip pages).
19+
20+
- `githelp list`
21+
Run `githelp` with the `list` subcommand. This prints the menu and shows all available tips from `tips.yml`.
22+
23+
24+
- `githelp explain [subcommand]`
25+
Use `explain` to see llama2 tips for a specific Git subcommand.
26+
For example:
27+
- `githelp explain status` to see help for `add`.
28+
- `githelp explain commit` to see help for `branch`.
29+
- `githelp explain status` to see help for `checkout`.
30+
- `githelp explain commit` to see help for `clone`.
31+
- `githelp explain status` to see help for `commit`.
32+
- `githelp explain commit` to see help for `fetch`.
33+
- `githelp explain status` to see help for `logs`.
34+
- `githelp explain commit` to see help for `pull`.
35+
- `githelp explain status` to see help for `push`.
36+
- `githelp explain commit` to see help for `rebase`.
37+
- `githelp explain status` to see help for `status`.
38+
- `githelp explain commit` to see help for `tag`.

‎docs/conf.py‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# -- Project information -----------------------------------------------------
2+
3+
project = 'Githelp'
4+
copyright = '2025, Jimmy Zhang'
5+
author = 'Jimmy Zhang'
6+
7+
8+
9+
# ----------------------------------------------------------------------------
10+
# Below here does not need to be edited for the lab
11+
# ----------------------------------------------------------------------------
12+
13+
# -- General configuration ---------------------------------------------------
14+
15+
# Add any Sphinx extension module names here, as strings. They can be
16+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
17+
# ones.
18+
extensions = [
19+
"myst_nb",
20+
'sphinx.ext.intersphinx',
21+
"sphinx_design",
22+
'sphinx.ext.autodoc',
23+
'sphinx.ext.napoleon',
24+
'sphinx_click'
25+
]
26+
27+
# "sphinxext.rediraffe",
28+
29+
# Add any paths that contain templates here, relative to this directory.
30+
templates_path = ['_templates']
31+
32+
# List of patterns, relative to source directory, that match files and
33+
# directories to ignore when looking for source files.
34+
# This pattern also affects html_static_path and html_extra_path.
35+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', "*import_posts*",
36+
"**/pandoc_ipynb/inputs/*", ".nox/*", "README.md",]
37+
38+
39+
# -- Options for HTML output -------------------------------------------------
40+
41+
# The theme to use for HTML and HTML Help pages. See the documentation for
42+
# a list of builtin themes.
43+
#
44+
html_theme = 'pydata_sphinx_theme'
45+
46+
47+
html_theme_options = {
48+
"show_nav_level": 2,
49+
"header_links_before_dropdown": 6,
50+
"icon_links": [
51+
{
52+
"name": "GitHub",
53+
"url": "https://github.com/compsys-progtools/githelp",
54+
"icon": "fa-brands fa-github",
55+
},
56+
{
57+
"name": "Course",
58+
"url": "https://github.com/compsys-progtools/githelp",
59+
"icon": "fa-solid fa-school",
60+
}],
61+
"secondary_sidebar_items": {
62+
"**/*": ["page-toc", "edit-this-page", "sourcelink"],
63+
}
64+
}
65+
66+
# html_favicon = "_static/favicon.ico"
67+
# change this to change the site title
68+
html_title = project
69+
70+
# Add any paths that contain custom static files (such as style sheets) here,
71+
# relative to this directory. They are copied after the builtin static files,
72+
# so a file named "default.css" will overwrite the builtin "default.css".
73+
html_static_path = ['_static']
74+
# html_extra_path = ["feed.xml"]
75+
# map pages to which sidebar they should have
76+
# "page_file_name": ["list.html", "of.html", "sidebar.html", "files.html"]
77+
html_sidebars = {
78+
"*": [],
79+
"**/*": ["sidebar-nav-bs",]
80+
}
81+
82+
# "about": ["hello.html"],
83+
# "publications": ["hello.html"],
84+
# "projects": ["hello.html"],
85+
# "resume": ["hello.html"],
86+
# "news": ["hello.html", 'archives.html'],
87+
# "news/**": ['postcard.html', 'recentposts.html', 'archives.html'],
88+
89+
90+
# Panels config
91+
panels_add_bootstrap_css = False
92+
93+
# MyST config
94+
myst_enable_extensions = [
95+
# "amsmath",
96+
"colon_fence",
97+
"deflist",
98+
"dollarmath",
99+
"fieldlist",
100+
"html_admonition",
101+
"html_image",
102+
# "linkify",
103+
"replacements",
104+
"smartquotes",
105+
"strikethrough",
106+
"substitution",
107+
# "tasklist",
108+
]
109+
110+
# def setup(app):
111+
# app.add_css_file("custom.css")

‎docs/developer_doc.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Developer Documentation
2+
3+
## Welcome to GitHelp
4+
5+
Learn Git faster, directly from your terminal, with friendly tips and optional AI powered explanations.
6+
7+
---
8+
## Description
9+
10+
Githelp is a command line tool designed to help CSC311 student understand and remember Git commands, while working through git. Instead of searching the web every time, you forget what `git status` or `git rebase` does, you can ask Githelp inside the terminal.
11+
12+
GitHelp reads from a set of tips which are stored in a YAML file and can also use an AI model (`llama2` one of Ollama model) to generate a more detail explanations when available. Whether you’re just starting with Git or brushing up on specific commands, GitHelp can help you on the fly.
13+
14+
With a focus on clarity, GitHelp aims to reduce frustration, support learning by doing, and make Git feel less intimidating.
15+
16+
---
17+
18+
## Installation
19+
You can start cloning to work locally or download directly from github.
20+
21+
### By clone
22+
23+
You can clone first
24+
```
25+
git clone https://github.com/compsys-progtools/githelp.git
26+
```
27+
28+
and then install
29+
```
30+
pip install githelp
31+
```
32+
(If you are using pip3)
33+
```
34+
pip3 install githelp
35+
```
36+
37+
For development purposes, you may want to install with pip's `-e` option
38+
39+
```
40+
pip install -e .
41+
```
42+
43+
To update, pull and install again.
44+
45+
The main use is as a CLI, for a list of all commands see the
46+
[CLI](cli.md) page.
47+
48+
## Structures
49+
50+
1. **CLI using Click library**
51+
- Implements the `githelp` command and subcommands (`list`, `explain`, `save`, and etc...).
52+
- Handles parsing arguments, options, and routing to the right functions.
53+
- [Click's library documentation](https://click.palletsprojects.com/en/stable/)
54+
55+
2. **`tips.yml` and the Yaml Library**
56+
- A YAML file that stores tip data in a dictionary format for each Git subcommand and can be found inside the data directory.
57+
- Each entry contains a `summary`, `when_to_use`, and `examples`.
58+
- [yaml's library documentation](https://pypi.org/project/PyYAML/)
59+
60+
3. **Rendering layer**
61+
- Functions that take the dictionaries and convert them into readable text for the terminal (Example - `render_overlay`, `render_menu` in overlays.py).
62+
63+
4. **AI integration**
64+
- When parsing the cmd `githelp explain <subcommand>` GitHelp calls a helper function to query the `llama2`.
65+
- If anything fails (Ollama not installed, model missing, network error), GitHelp falls back to the standard tips(tips.yml).
66+
- The model's prompts can be changed to developer's preference.
67+
- The model's prompts in this are specialized for particular command.
68+
- The model can also be changed to developer's preference, however the current default is set to `llama2`

‎docs/index.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!-- .. Computer Systems and Programming Tools utils documentation primary file, created by
2+
sphinx-quickstart on Fri Dec 23 10:42:13 2022.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive. -->
5+
6+
# Githelp
7+
8+
## <u>Purpose</u>
9+
GitHelp is a command line tool that helps CSC 311 students learn Git. It provides tips for common Git subcommands from a shared tips.yml file and can use an Ollama ai (model llama2) to give more detailed explanations. The goal of the project is to make Git feel less confusing and more approachable.
10+
11+
## <u>Usage</u>
12+
13+
The main use is as a CLI, for a list of all commands see the
14+
[CLI](cli.md) page.
15+
16+
17+
```{toctree}
18+
:caption: Table of Contents
19+
:maxdepth: 2
20+
21+
cli
22+
developer_doc
23+
user_doc
24+
api
25+
```
26+
27+
<!--
28+
Indices and tables
29+
==================
30+
31+
* :ref:`genindex`
32+
* :ref:`modindex`
33+
* :ref:`search` -->

‎docs/logo.png‎

37.2 KB
Loading

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)