Documentation updates (#167)

* feat(cli): migrate to uv package manager.

* docs(cli): Add migration guide from `pipx` to `uv`

* Auto generate docs

* docs(cli): add `--index-strategy unsafe-best-match` to CPU-only installation guide

* docs(cli): fix typo in installation instructions and change heading layout.

* docs(nvim): update neovim version in docs

* Auto generate docs

---------

Co-authored-by: Davidyz <[email protected]>

Author: Davidyz

.github/ISSUE_TEMPLATE/bug_report.md

@@ -36,7 +36,9 @@ attach the relevant config here:
 ```
 
 **Platform information:**
- - If the issue is about the CLI, attach the output of `pipx runpip vectorcode freeze`:
+ - If the issue is about the CLI, attach a list of packages in the Python virtual environment:
+   - for `pipx`, run `pipx runpip vectorcode freeze`;
+   - for `uv`, run `uv tool run --from=vectorcode python -m ensurepip && uv tool run --from=vectorcode python -m pip freeze`.
 ```
 
 ```

.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,18 @@
+---
+name: Enhancement
+about: Discuss what new features can be added, or existing features improved.
+title: "[FEAT]"
+labels: enhancement
+assignees: ''
+
+---
+
+**Describe the feature you want**
+
+> Tell me about the feature, ideally with a scenario where this feature would be
+useful.
+
+**Complimentary Material**
+
+> If there's any material that may help me implement/test this feature, please
+list them here.

doc/VectorCode.txt

@@ -82,16 +82,15 @@ you can use the following plugin spec:
     {
       "Davidyz/VectorCode",
       version = "*",
-      build = "pipx upgrade vectorcode", -- recommended if you set `version = "*"` or follow the main branch
+      build = "uv tool upgrade vectorcode", -- This helps keeping the CLI up-to-date
+      -- build = "pipx upgrade vectorcode", -- If you used pipx to install the CLI
       dependencies = { "nvim-lua/plenary.nvim" },
     }
 <
 
 
-  This plugin is developed and tested (sort of) under the latest stable release
-  (specifically the package provided in the Extra
-  <https://archlinux.org/packages/extra/x86_64/neovim/> repository of Arch
-  Linux).
+  This plugin is developed and tested on neovim _v0.11_. It may work on older
+  versions, but I do not test on them before publishing.
 
 NIX ~
 

docs/cli.md

@@ -5,8 +5,9 @@
 
 * [Installation](#installation)
   * [Install from Source](#install-from-source)
+  * [Migration from `pipx`](#migration-from-pipx)
   * [Chromadb](#chromadb)
-    * [For Windows Users](#for-windows-users)
+  * [For Windows Users](#for-windows-users)
   * [Legacy Environments](#legacy-environments)
   * [Nix](#nix)
 * [Getting Started](#getting-started)
@@ -44,42 +45,50 @@ compiler because the core components of the vector database (ChromaDB) contains
 c++ and rust code.
 
 The recommended way of
-installation is through [`pipx`](https://pipx.pypa.io/stable/), which will
+installation is through [`uv`](https://docs.astral.sh/uv/), which will
 create a virtual environment for the package itself that doesn't mess up with
 your system Python or project-local virtual environments.
 
-After installing `pipx`, run:
+After installing `uv`, run:
 ```bash
-pipx install vectorcode
+uv tool install vectorcode
 ```
 in your shell. To specify a particular version of Python, use the `--python` 
-flag. For example, `pipx install vectorcode --python python3.11`. For hardware
+flag. For example, `uv tool install vectorcode --python python3.11`. For hardware
 accelerated embedding, refer to [the relevant section](#hardware-acceleration).
-If you want a cpu-only installation without CUDA dependences required by 
-default by pytorch, run:
+If you want a CPU-only installation without CUDA dependencies required by 
+default by PyTorch, run:
 ```bash
-PIP_INDEX_URL="https://download.pytorch.org/whl/cpu" PIP_EXTRA_INDEX_URL="https://pypi.org/simple" pipx install vectorcode
+uv tool install vectorcode --index https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match
 ```
 
 If you need to install multiple dependency group (for [LSP](#lsp-mode) or
 [MCP](#mcp-server)), you can use the following syntax:
 ```bash
-pipx install vectorcode[lsp,mcp]
+uv tool install vectorcode[lsp,mcp]
 ```
 > [!NOTE] 
 > The command only install VectorCode and `SentenceTransformer`, the default
-> embedding engine. To use a different embedding function supported by Chromadb,
-> you may need to use `pipx inject` to install extra dependences to the virtual
-> environment that `pipx` creates for VectorCode. This may include OpenAI,
-> Ollama and other self/cloud-hosted embedding model providers.
+> embedding engine. If you need to install an extra dependency, you can use 
+> `uv tool install vectorcode --with <your_deps_here>`
 
 ### Install from Source
-To install from source, either `git clone` this reposority and run `pipx install
-<path_to_vectorcode_repo>`, or use the git URL:
+To install from source, either `git clone` this repository and run `uv tool install
+<path_to_vectorcode_repo>`, or use `pipx`:
 ```bash
 pipx install git+https://github.com/Davidyz/VectorCode
 ```
 
+### Migration from `pipx`
+
+The motivation behind the change from `pipx` to `uv tool` is mainly the
+performance. The caching mechanism in uv makes it a lot faster than `pipx` for a
+lot of operations. If you installed VectorCode via `pipx`, you can continue to
+use `pipx` to manage your VectorCode installation. If you wish to switch to
+`uv`, you need to uninstall VectorCode using `pipx` and then use `uv` to install
+it as described above. All your VectorCode configurations and database files
+will work out of the box on your new install.
+
 ### Chromadb
 [Chromadb](https://www.trychroma.com/) is the vector database used by VectorCode
 to store and retrieve the code embeddings. Although it is already bundled with
@@ -94,19 +103,19 @@ will significantly reduce the IO overhead and avoid potential race condition.
 > ChromaDB recently released v1.0.0, which may not work with VectorCode. I'm
 > testing with v1.0.0 and will publish a new release when it's ready.
 
-#### For Windows Users
+### For Windows Users
 
 Windows support is not officially tested at this moment. [This PR](https://github.com/Davidyz/VectorCode/pull/40)
 tracks my progress trying to provide better experiences for windows users.
 
 ### Legacy Environments
 
 If your environment doesn't support `numpy` version 2.0+, the default,
-unconstrained numpy picked by `pipx` may not work for you. In this case, you can
-try installing the package by `pipx install vectorcode[legacy]`, which enforces 
+unconstrained numpy may not work for you. In this case, you can
+try installing the package by `uv tool install vectorcode[legacy]`, which enforces 
 numpy `v1.x`. If this doesn't help, please open an issue with your OS, CPU
 architecture, python version and the vectorcode virtual environment 
-(`pipx runpip vectorcode freeze`).
+(`uv tool run --from=vectorcode python -m ensurepip && uv tool run --from=vectorcode python -m pip freeze`).
 
 ### Nix
 

docs/neovim.md

@@ -71,15 +71,14 @@ you can use the following plugin spec:
 {
   "Davidyz/VectorCode",
   version = "*",
-  build = "pipx upgrade vectorcode", -- recommended if you set `version = "*"` or follow the main branch
+  build = "uv tool upgrade vectorcode", -- This helps keeping the CLI up-to-date
+  -- build = "pipx upgrade vectorcode", -- If you used pipx to install the CLI
   dependencies = { "nvim-lua/plenary.nvim" },
 }
 ```
 
-> This plugin is developed and tested (sort of) under the latest stable release
-> (specifically the package provided in the 
-> [Extra](https://archlinux.org/packages/extra/x86_64/neovim/) 
-> repository of Arch Linux).
+> This plugin is developed and tested on neovim _v0.11_. It may work on older
+> versions, but I do not test on them before publishing.
 
 ### Nix