From e7a98f30192c7d46a7809d5300a8ee98643ea713 Mon Sep 17 00:00:00 2001 From: coder3101 Date: Sat, 11 Jan 2025 16:24:35 +0530 Subject: [PATCH] update readme --- README.md | 113 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 65 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 51a3746..06e6fca 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,77 @@ # Protols - Protobuf Language Server -[![Crates.io](https://img.shields.io/crates/v/protols.svg)](https://crates.io/crates/protols) +[![Crates.io](https://img.shields.io/crates/v/protols.svg)](https://crates.io/crates/protols) [![Build and Test](https://github.com/coder3101/protols/actions/workflows/ci.yml/badge.svg)](https://github.com/coder3101/protols/actions/workflows/ci.yml) -**Protols** is an open-source Language Server Protocol (LSP) for **proto** files, powered by the robust and efficient [tree-sitter](https://tree-sitter.github.io/tree-sitter/) parser. With Protols, you get powerful code assistance for protobuf files, including auto-completion, syntax diagnostics, and more. +**Protols** is an open-source, feature-rich [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) for **Protocol Buffers (proto)** files. Powered by the efficient [tree-sitter](https://tree-sitter.github.io/tree-sitter/) parser, Protols offers intelligent code assistance for protobuf development, including features like auto-completion, diagnostics, formatting, and more. -![](./assets/protols.mov) +![Protols Demo](./assets/protols.mov) ## ✨ Features -- ✅ Code Completion -- ✅ Diagnostics -- ✅ Document Symbols -- ✅ Code Formatting -- ✅ Go to Definition -- ✅ Hover Information -- ✅ Rename Symbols -- ✅ Find references +- ✅ **Code Completion**: Auto-complete messages, enums, and keywords in your `.proto` files. +- ✅ **Diagnostics**: Syntax errors detected with the tree-sitter parser. +- ✅ **Document Symbols**: Navigate and view all symbols, including messages and enums. +- ✅ **Code Formatting**: Format `.proto` files using `clang-format` for a consistent style. +- ✅ **Go to Definition**: Jump to the definition of symbols like messages or enums. +- ✅ **Hover Information**: Get detailed information and documentation on hover. +- ✅ **Rename Symbols**: Rename protobuf symbols and propagate changes across the codebase. +- ✅ **Find References**: Find where messages, enums, and fields are used throughout the codebase. + +--- ## Table of Contents - [Installation](#installation) + - [For Neovim](#for-neovim) + - [For Visual Studio Code](#for-visual-studio-code) - [Configuration](#configuration) - [Basic Configuration](#basic-configuration) - [Experimental Configuration](#experimental-configuration) - [Formatter Configuration](#formatter-configuration) + - [Multiple Configuration Files](#multiple-configuration-files) - [Usage](#usage) + - [Code Completion](#code-completion) + - [Diagnostics](#diagnostics) + - [Code Formatting](#code-formatting) + - [Document Symbols](#document-symbols) + - [Go to Definition](#go-to-definition) + - [Hover Information](#hover-information) + - [Rename Symbols](#rename-symbols) + - [Find References](#find-references) - [Contributing](#contributing) + - [Setting Up Locally](#setting-up-locally) - [License](#license) --- -### Installation +## 🚀 Installation -#### For Neovim +### For Neovim -You can install [protols with mason.nvim](https://github.com/mason-org/mason-registry/blob/main/packages/protols/package.yaml) or directly from crates.io with: +You can install **Protols** via [mason.nvim](https://github.com/mason-org/mason-registry/blob/main/packages/protols/package.yaml), or install it directly from [crates.io](https://crates.io/crates/protols): ```bash cargo install protols ``` -Then, configure it with [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#protols): +Then, configure it in your `init.lua` using [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig): ```lua require'lspconfig'.protols.setup{} ``` -#### For Visual Studio Code - -You can use the [Protobuf Language Support](https://marketplace.visualstudio.com/items?itemName=ianandhum.protobuf-support) extension, which leverages this LSP under the hood. +### For Visual Studio Code -> **Note:** This extension is [open source](https://github.com/ianandhum/vscode-protobuf-support) but is not maintained by us. -You can install **protols** via your preferred method, such as downloading the binary or building from source. Here’s how to get started with the simplest method: +If you're using Visual Studio Code, you can install the [Protobuf Language Support](https://marketplace.visualstudio.com/items?itemName=ianandhum.protobuf-support) extension, which uses this LSP under the hood. +> **Note**: This extension is [open source](https://github.com/ianandhum/vscode-protobuf-support), but is not officially maintained by us. --- -## Configuration +## ⚙️ Configuration -Protols is configured using a `protols.toml` file. This configuration file can be placed in any directory, and **protols** will look for the closest file by recursively searching through parent directories. - -Here’s a sample configuration: +Protols is configured using a `protols.toml` file, which you can place in any directory. **Protols** will search for the closest configuration file by recursively traversing the parent directories. ### Sample `protols.toml` @@ -83,87 +93,94 @@ clang_format_path = "/usr/bin/clang-format" # clang-format binary to execute in The `[config]` section contains stable settings that should generally remain unchanged. -- `include_paths`: List the directories where your `.proto` files are located. -- `disable_parse_diagnostics`: Set to `true` to disable parsing diagnostics. +- `include_paths`: Directories to search for `.proto` files. +- `disable_parse_diagnostics`: Set to `true` to disable diagnostics during parsing. #### Experimental Configuration -The `[config.experimental]` section contains settings that are still under development or are not fully tested. +The `[config.experimental]` section contains settings that are in development or not fully tested. -- `use_protoc_diagnostics`: If set to `true`, this will enable diagnostics from the `protoc` compiler. +- `use_protoc_diagnostics`: Enable diagnostics from the `protoc` compiler when set to `true`. #### Formatter Configuration -The `[formatter]` section configures how the formatting is done. +The `[formatter]` section allows configuration for code formatting. -- `clang_format_path`: Path to the `clang-format` binary used for formatting `.proto` files. +- `clang_format_path`: Specify the path to the `clang-format` binary. ### Multiple Configuration Files -You can use multiple `protols.toml` files across different directories, and **protols** will use the closest configuration file found by traversing the parent directories. +You can place multiple `protols.toml` files across different directories. **Protols** will use the closest configuration file by searching up the directory tree. --- ## 🛠️ Usage +Protols offers a rich set of features to enhance your `.proto` file editing experience. + ### Code Completion -Protols provides intelligent autocompletion for messages, enums, and proto3 keywords within the current package. +**Protols** offers intelligent autocompletion for messages, enums, and proto3 keywords within the current package. Simply start typing, and Protols will suggest valid completions. ### Diagnostics -Diagnostics are powered by the tree-sitter parser, which catches syntax errors but does not utilize `protoc` for more advanced error reporting. +Syntax errors are caught by the tree-sitter parser, which highlights issues directly in your editor. For more advanced error reporting, the LSP can be configured to use `protoc` diagnostics. ### Code Formatting -Formatting is enabled if [clang-format](https://clang.llvm.org/docs/ClangFormat.html) is available. You can control the [formatting style](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) by placing a `.clang-format` file in the root of your workspace. Both document and range formatting are supported. +Format your `.proto` files using `clang-format`. To customize the formatting style, add a `.clang-format` file to the root of your project. Both document and range formatting are supported. ### Document Symbols -Provides symbols for the entire document, including nested symbols, messages, and enums. +Protols provides a list of symbols in the current document, including nested symbols such as messages and enums. This allows for easy navigation and reference. ### Go to Definition -Jump to the definition of any custom symbol, even across package boundaries. +Jump directly to the definition of any custom symbol, including those in other files or packages. This feature works across package boundaries. ### Hover Information -Displays comments and documentation for protobuf symbols on hover. Works seamlessly across package boundaries. +Hover over any symbol to get detailed documentation and comments associated with it. This works seamlessly across different packages and namespaces. ### Rename Symbols -Allows renaming of symbols like messages and enums, along with all their usages across packages. Currently, renaming fields within symbols is not supported directly. +Rename symbols like messages or enums, and Propagate the changes throughout the codebase. Currently, field renaming within symbols is not supported. ### Find References -Allows user defined types like messages and enums can be checked for references. Nested fields are completely supported. +Find all references to user-defined types like messages or enums. Nested fields are fully supported, making it easier to track symbol usage across your project. --- -## Contributing +## 🤝 Contributing -We welcome contributions from the community! If you’d like to help improve **protols**, here’s how you can get started: +We welcome contributions from developers of all experience levels! To get started: -1. Fork the repository and clone it to your machine. -2. Make your changes in a new branch. -3. Run the tests to ensure everything works properly. -4. Open a pull request with a description of the changes. +1. **Fork** the repository and clone it to your local machine. +2. Create a **new branch** for your feature or fix. +3. Run the tests to ensure everything works as expected. +4. **Open a pull request** with a detailed description of your changes. ### Setting Up Locally 1. Clone the repository: + ```bash git clone https://github.com/coder3101/protols.git cd protols ``` -2. Build and test your changes: +2. Build and test the project: + ```bash cargo build cargo test ``` + --- -## License +## 📄 License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details. + +---