# 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.
## 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`.
## 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "doc-lsp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "documentation, hover, language-server, lsp, markdown",
"author": null,
"author_email": "Bruno Rocha <rochacbruno@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/22/b1/941837261a57a24a278ece61efa93b3e76af389ba6ac2b8d55264f863843/doc_lsp-0.1.0.tar.gz",
"platform": null,
"description": "# doc-lsp\n\n[](https://github.com/rochacbruno/doc_lsp/actions/workflows/test.yml)\n[](https://codecov.io/gh/rochacbruno/doc_lsp)\n[](https://www.python.org/downloads/)\n[](https://github.com/rochacbruno/doc_lsp/blob/main/LICENSE)\n\ndoc-lsp is a simple specification and LSP (Language Server) that loads comments from a separate file.\n\nDocument variables in a separate markdown file and this LSP will show the docs on your editor.\n\n## Standard\n\nAssuming a file named `settings.py` \n\n```py\nSERVER = \"localhost\"\nPORT = 4545\n```\n\nOr a `config.conf`\n\n```conf\nmax_open_windows true\nfont_size 18\n```\n\nThen the LSP will lookup information about each variable on a separate file.\n\n`settings.py.md`\n```markdown\n## SERVER\n> This variable defines which server the system is connected to, \n> when used together with port this will define the connection string. \n> example: `hostname:port` \n\n## PORT\n> Port used to connect ot server\n\n```\n\n`config.conf.md`\n```markdown\n## max_open_windows\n> This variable is used to set how many multiple tiles can be opened\n> at the same time.\n\n## font_size = 18\n> Set the default size for the system font.\n```\n\n## Usage\n\nWith the LSP Server `doc-lsp` enabled on your editor,\nhaving the variable selected or with cursor focus, trigger the action `view_doc` \nand the editor will show the overlay with the full text from the respective comment file.\n\n`|` = mouse cursor position\n```py\nSERV|ER = \"foo\"\n```\n\nHovering the mouse over the variable will show the documentation.\n\n```plain\nSERV|ER = \"foo\"\n _________________________________________________________________________\n | SERVER |\n | This variable defines which server the system is connected to, |\n | when used together with port this will define the connection string. |\n | example: `hostname:port` |\n _________________________________________________________________________\n```\n\nIf the `settings.py.md` does not exist, then the action will be NOOP and just emit a INFO `Doc not found for variable`.\n\n\n## Implementation\n\n- The doc-lsp is implemented in Python\n- It is designed to run from `uv`\n- 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.\n\n## Specs\n\n- doc-lsp is filetype agnostic\n- doc-lsp lookup will match `filename.ext` -> `filename.ext.md`\n- Lookup is made from the doc-lsp parser\n- The last occurence wins in case of duplication\n\n \nSee [./examples](examples) \n\n\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Language Server Protocol implementation for loading documentation from separate markdown files",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"documentation",
" hover",
" language-server",
" lsp",
" markdown"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0f1e7ebccc6e2227df5fc12dca2dc07800671b677761aca1a611cbef48376faf",
"md5": "9cbd13fad117975811f8695463cbc9fc",
"sha256": "abd07a1a8ce6a1e0484780eedab01b592b399c2ac6e543bfc7b4905775474e4a"
},
"downloads": -1,
"filename": "doc_lsp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cbd13fad117975811f8695463cbc9fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 21449,
"upload_time": "2025-08-19T01:49:18",
"upload_time_iso_8601": "2025-08-19T01:49:18.513488Z",
"url": "https://files.pythonhosted.org/packages/0f/1e/7ebccc6e2227df5fc12dca2dc07800671b677761aca1a611cbef48376faf/doc_lsp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "22b1941837261a57a24a278ece61efa93b3e76af389ba6ac2b8d55264f863843",
"md5": "2f2c4df97e4320109fbbfe0420b40487",
"sha256": "b32c7bc2e50eb5fad2a9fae01bc571dc46156f50e212ab28e0380783f1973bbe"
},
"downloads": -1,
"filename": "doc_lsp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2f2c4df97e4320109fbbfe0420b40487",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 54313,
"upload_time": "2025-08-19T01:49:20",
"upload_time_iso_8601": "2025-08-19T01:49:20.296155Z",
"url": "https://files.pythonhosted.org/packages/22/b1/941837261a57a24a278ece61efa93b3e76af389ba6ac2b8d55264f863843/doc_lsp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 01:49:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "doc-lsp"
}
JSON