docs: add Read the Docs configuration for online documentation

.gitignore

@@ -32,3 +32,7 @@ Thumbs.db
 
 # Build artifacts
 *.log
+
+
+#docs
+/docs/_build/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,14 @@
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"

docs/_static/custom.css

@@ -0,0 +1,13 @@
+/* Furo-specific polish (works in both light and dark modes). */
+:root {
+  --content-width: 980px;
+}
+
+img {
+  border-radius: 6px;
+}
+
+main table {
+  display: block;
+  overflow-x: auto;
+}

docs/commands.md

@@ -0,0 +1,142 @@
+# Commands
+
+`ghgrab` supports interactive usage and three command groups: `release`, `agent`, and `config`.
+
+## Base command
+
+```bash
+ghgrab [URL] [--cwd] [--no-folder] [--token TOKEN]
+```
+
+### Global options
+
+| Flag | Description |
+| --- | --- |
+| `--cwd` | Download files to the current working directory |
+| `--no-folder` | Download directly into the target directory without a repository subfolder |
+| `--token <TOKEN>` | Use a one-time GitHub token without storing it |
+
+## Release downloads
+
+The `release` command, with alias `rel`, downloads release assets from a repository:
+
+```bash
+ghgrab rel <owner/repo> [OPTIONS]
+```
+
+### Common examples
+
+```bash
+# Download the best matching artifact
+ghgrab rel sharkdp/bat
+
+# Download a specific release tag
+ghgrab rel sharkdp/bat --tag v0.25.0
+
+# Allow prereleases when selecting the latest release
+ghgrab rel starship/starship --prerelease
+
+# Force an exact asset with regex
+ghgrab rel sharkdp/bat --asset-regex "x86_64.*windows.*zip"
+
+# Extract archives after download
+ghgrab rel sharkdp/bat --extract
+
+# Install an extracted binary into a target directory
+ghgrab rel sharkdp/bat --extract --bin-path ~/.local/bin
+```
+
+### Release options
+
+| Flag | Description |
+| --- | --- |
+| `--tag <TAG>` | Download a specific release tag |
+| `--prerelease` | Allow prereleases when `--tag` is not provided |
+| `--asset-regex <REGEX>` | Match a specific release asset |
+| `--os <OS>` | Override detected operating system |
+| `--arch <ARCH>` | Override detected architecture |
+| `--file-type <TYPE>` | Prefer `any`, `archive`, or `binary` assets |
+| `--extract` | Extract archive assets after download |
+| `--out <DIR>` | Use a custom output directory |
+| `--bin-path <DIR>` | Install the selected file or binary into the provided directory |
+| `--cwd` | Download into the current working directory |
+| `--token <TOKEN>` | Use a one-time GitHub token for this run |
+
+### Selection behavior
+
+- If one asset clearly matches the current platform, `ghgrab` downloads it immediately.
+- If several close matches exist, `ghgrab` shows an interactive picker.
+- If no assets match the filters, the command exits with an error.
+
+## Agent mode
+
+The `agent` command is designed for non-interactive tooling. It prints a stable JSON envelope with:
+
+- `api_version`
+- `ok`
+- `command`
+- `data` on success
+- `error` on failure
+
+### Fetch a repository tree
+
+```bash
+ghgrab agent tree https://github.com/rust-lang/rust
+```
+
+### Download specific paths
+
+```bash
+ghgrab agent download https://github.com/rust-lang/rust src/tools README.md --out ./tmp
+```
+
+### Download a subtree
+
+```bash
+ghgrab agent download https://github.com/rust-lang/rust --subtree src/tools --out ./tmp
+```
+
+### Download the entire repository
+
+```bash
+ghgrab agent download https://github.com/rust-lang/rust --repo --out ./tmp
+```
+
+### Agent command rules
+
+- `agent download --repo` cannot be combined with positional paths.
+- `agent download --repo` cannot be combined with `--subtree`.
+- `agent download --subtree` cannot be combined with positional paths.
+
+### Agent options
+
+#### `agent tree`
+
+| Flag | Description |
+| --- | --- |
+| `--token <TOKEN>` | Use a one-time GitHub token |
+
+#### `agent download`
+
+| Flag | Description |
+| --- | --- |
+| `--repo` | Download the entire repository |
+| `--subtree <PATH>` | Download one subtree path |
+| `--cwd` | Download into the current working directory |
+| `--no-folder` | Skip the repository subfolder |
+| `--out <DIR>` | Use a custom output directory |
+| `--token <TOKEN>` | Use a one-time GitHub token |
+
+## Configuration
+
+The `config` command manages saved settings:
+
+```bash
+ghgrab config set token YOUR_TOKEN
+ghgrab config set path "/your/custom/path"
+ghgrab config list
+ghgrab config unset token
+ghgrab config unset path
+```
+
+`config list` masks stored tokens before printing them.

docs/conf.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+project = "GhGrab"
+author = "abhixdd"
+copyright = "2026, abhixdd"
+release = "1.3.1"
+version = release
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autosectionlabel",
+    "qiskit_sphinx_theme",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+root_doc = "index"
+
+html_theme = "qiskit-ecosystem"
+html_title = "ghgrab - grab anything you want"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+autosectionlabel_prefix_document = True
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+
+rst_prolog = """
+.. |project| replace:: GhGrab
+"""
+
+BASE_DIR = Path(__file__).resolve().parent

docs/configuration.md

@@ -0,0 +1,58 @@
+# Configuration
+
+`ghgrab` supports both saved configuration and one-off overrides.
+
+## Saved settings
+
+Use the `config` command to store values locally:
+
+```bash
+ghgrab config set token YOUR_TOKEN
+ghgrab config set path "/your/custom/path"
+```
+
+Show the current configuration:
+
+```bash
+ghgrab config list
+```
+
+Remove a saved value:
+
+```bash
+ghgrab config unset token
+ghgrab config unset path
+```
+
+## GitHub authentication
+
+You can provide a token in three ways:
+
+1. with `--token <TOKEN>` for a single command,
+2. with a saved config token,
+3. with an environment variable.
+
+Supported environment variables:
+
+- `GHGRAB_GITHUB_TOKEN`
+- `GITHUB_TOKEN`
+
+The command-line flag takes precedence over environment variables, and environment variables take precedence over saved config.
+
+## Download destination
+
+You can control where files are written by using:
+
+- `ghgrab config set path ...` for a saved default,
+- `--out <DIR>` for command-specific output,
+- `--cwd` to force downloads into the current working directory.
+
+Use `--no-folder` when you want downloaded paths placed directly in the target directory instead of a repository-named folder.
+
+## When a token helps
+
+GitHub token support is especially useful when:
+
+- you hit anonymous API rate limits,
+- you are scripting against private repositories that your token can access,
+- you want more reliable automation in CI or agent workflows.

docs/contributing.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Contributions are welcome through issues and pull requests.
+
+## Report bugs
+
+When reporting a bug, include:
+
+- your operating system,
+- your terminal emulator,
+- clear reproduction steps,
+- any relevant error output or screenshots.
+
+## Suggest enhancements
+
+If you want to propose a feature or UX improvement, open an issue first so the approach can be discussed before implementation.
+
+## Pull request flow
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Make the change and add tests when appropriate.
+4. Run the local checks.
+5. Open a pull request.
+
+## Design expectations
+
+The project favors:
+
+- responsive terminal interactions,
+- cross-platform behavior,
+- polished TUI details such as search, previews, and feedback states.
+
+For broader contribution guidance, see the repository root `CONTRIBUTING.md`.

docs/development.md

@@ -0,0 +1,52 @@
+# Development
+
+## Local setup
+
+To build `ghgrab` locally you need a working Rust toolchain.
+
+```bash
+git clone https://github.com/abhixdd/ghgrab.git
+cd ghgrab
+cargo build
+```
+
+Run the TUI locally:
+
+```bash
+cargo run
+```
+
+## Test and quality checks
+
+Run the project's test and quality commands before submitting changes:
+
+```bash
+cargo test
+cargo fmt
+cargo clippy
+```
+
+## Package layout
+
+The repository currently includes:
+
+- a Rust application under `src/`,
+- Rust integration tests under `tests/`,
+- a Python launcher package under `ghgrab/`,
+- packaging metadata for Cargo, npm, Python, Nix, and Arch Linux.
+
+## Documentation workflow
+
+The documentation is built with Sphinx and the Read the Docs theme.
+
+Install the docs dependencies:
+
+```bash
+python -m pip install -r docs/requirements.txt
+```
+
+Build the HTML site:
+
+```bash
+sphinx-build -b html docs docs/_build/html
+```