https://github.com/rochacbruno/doc_lsp
Document variables in a separate md text file and this LSP will show the docs on your editor.
https://github.com/rochacbruno/doc_lsp
configuration documentation language-server-protocol lsp lsp-server markdown settings vim-lsp vscode-extension vscode-lsp
Last synced: 4 months ago
JSON representation
Document variables in a separate md text file and this LSP will show the docs on your editor.
- Host: GitHub
- URL: https://github.com/rochacbruno/doc_lsp
- Owner: rochacbruno
- License: agpl-3.0
- Created: 2025-08-18T16:21:08.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-20T20:14:24.000Z (9 months ago)
- Last Synced: 2025-09-14T23:56:17.802Z (8 months ago)
- Topics: configuration, documentation, language-server-protocol, lsp, lsp-server, markdown, settings, vim-lsp, vscode-extension, vscode-lsp
- Language: Python
- Homepage:
- Size: 469 KB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# doc-lsp
[](https://github.com/rochacbruno/doc_lsp/actions/workflows/test.yml)
[](https://codecov.io/gh/rochacbruno/doc_lsp)
[](https://www.python.org/downloads/)
[](https://github.com/rochacbruno/doc_lsp/blob/main/LICENSE)
doc-lsp is a simple specification and LSP (Language Server) that loads comments from a separate file.
Document variables in a separate markdown file and this LSP will show the docs on your editor.
Works on:
- Python
- YAML
- JSON
- TOML
- INI
- Properties
- Conf
- .env files
- and more...
## Standard
Assuming a file named `settings.py`
```py
SERVER = "localhost"
PORT = 4545
```
Or a `config.conf`
```conf
max_open_windows true
font_size 18
```
Then the LSP will lookup information about each variable on a separate file.
`settings.py.md`
```markdown
## SERVER
> This variable defines which server the system is connected to,
> when used together with port this will define the connection string.
> example: `hostname:port`
## PORT
> Port used to connect ot server
```
`config.conf.md`
```markdown
## max_open_windows
> This variable is used to set how many multiple tiles can be opened
> at the same time.
## font_size = 18
> Set the default size for the system font.
```
## Usage
With the LSP Server `doc-lsp` enabled on your editor,
having the variable selected or with cursor focus, trigger the action `view_doc`
and the editor will show the overlay with the full text from the respective comment file.
`|` = mouse cursor position
```py
SERV|ER = "foo"
```
Hovering the mouse over the variable will show the documentation.
```plain
SERV|ER = "foo"
_________________________________________________________________________
| SERVER |
| This variable defines which server the system is connected to, |
| when used together with port this will define the connection string. |
| example: `hostname:port` |
_________________________________________________________________________
```
If the `settings.py.md` does not exist, then the action will be NOOP and just emit a INFO `Doc not found for variable`.
## Installation
### Install the Language Server
```bash
# Using pip
pip install doc-lsp
# Using uv
uv tool install doc-lsp
# From source
git clone https://github.com/rochacbruno/doc_lsp.git
cd doc_lsp
uv pip install -e .
```
### Editor Integration
#### VS Code Extension
The easiest way to use doc-lsp in VS Code is with the official extension:
1. **Build and install the extension**:
```bash
cd code/doc-lsp-vscode
npm install
npm run package
code --install-extension doc-lsp-*.vsix
```
2. **Configure** (optional):
```json
{
"docLsp.enabled": true,
"docLsp.serverPath": "doc-lsp",
"docLsp.additionalFileExtensions": [".cfg", ".env"]
}
```
See [code/doc-lsp-vscode/README.md](code/doc-lsp-vscode/README.md) for detailed instructions.
#### Generic LSP Proxy (Alternative for VS Code)
You can also use the [Generic LSP Proxy](https://marketplace.visualstudio.com/items?itemName=statiolake.vscode-generic-lsp-proxy) extension:
1. Install the extension
2. Create `.vscode/lsp-proxy.json` in your workspace (see example in `.vscode/lsp-proxy.json`)
3. Reload VS Code
#### Other Editors
doc-lsp implements the Language Server Protocol and can be used with any LSP-compatible editor.
See the comprehensive [Editor Setup Guide](EDITORS_SETUP.md) for detailed instructions on configuring:
- **Helix** - Modern modal editor with built-in LSP support
- **Neovim** - Using nvim-lspconfig
- **Zed** - High-performance collaborative editor
- **Emacs** - Using lsp-mode or eglot
- **Sublime Text** - Using LSP package
- **Kate** - See dedicated [Kate Setup Guide](KATE_SETUP.md)
## Implementation
- The doc-lsp is implemented in Python
- It is designed to run from `uv`
- It will cache the documentation for each variable, so if the file is not changed, the documentation will be read from the cache, it can use `workspace/didChangeWatchedFiles` to invalidate the cache.
## Specs
- doc-lsp is filetype agnostic
- doc-lsp lookup will match `filename.ext` -> `filename.ext.md`
- Lookup is made from the doc-lsp parser
- The last occurence wins in case of duplication
See [./examples](examples)