Skip to content

Commit d25f483

Browse files
mceplmcepl
committed
doc: Comprehensive rewrite documentation to cover whole plugin
- Add automatic documentation build and deployment to GitHub Pages - Add rename configuration guide with examples - Update README with concise documentation and links to RTD - Add docs optional dependencies to pyproject.toml - Add .readthedocs.yaml configuration file - Add comprehensive test suite demonstrating configuration patterns of the rename functionality Fixes: #29 Signed-off-by: Matěj Cepl <[email protected]>
1 parent e30a4d1 commit d25f483

File tree

14 files changed

+1728
-136
lines changed

14 files changed

+1728
-136
lines changed

‎.github/workflows/python-publish.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,16 @@ jobs:
3333
- name: Publish package
3434
if: startsWith(github.ref, 'refs/tags')
3535
uses: pypa/gh-action-pypi-publish@81e9d935c883d0b210363ab89cf05f3894778450
36+
- name: Build documentation
37+
if: startsWith(github.ref, 'refs/tags')
38+
run: |
39+
cd doc
40+
pip install sphinx sphinx-rtd-theme myst-parser
41+
sphinx-build -b html . _build/html
42+
- name: Deploy documentation
43+
if: startsWith(github.ref, 'refs/tags')
44+
uses: peaceiris/actions-gh-pages@v3
45+
with:
46+
github_token: ${{ secrets.GITHUB_TOKEN }}
47+
publish_dir: ./doc/_build/html
48+
destination_dir: docs

‎.readthedocs.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
version: 2
6+
7+
# Set the OS, Python version and other tools you might need
8+
build:
9+
os: ubuntu-22.04
10+
tools:
11+
python: "3.9"
12+
13+
# Build documentation in the "doc/" directory with Sphinx
14+
sphinx:
15+
configuration: doc/conf.py
16+
17+
# Optionally declare the Python requirements required to build your docs
18+
python:
19+
install:
20+
- requirements: doc/requirements.txt

‎README.md‎

Lines changed: 65 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -2,170 +2,101 @@
22

33
[![Tests](https://github.com/python-rope/pylsp-rope/actions/workflows/run-test.yml/badge.svg)](https://github.com/python-rope/pylsp-rope/actions/workflows/run-test.yml)
44
[![codecov](https://codecov.io/gh/python-rope/pylsp-rope/graph/badge.svg?token=LMO7PW0AEK)](https://codecov.io/gh/python-rope/pylsp-rope)
5+
[![Documentation](https://readthedocs.org/projects/pylsp-rope/badge/?version=latest)](https://pylsp-rope.readthedocs.io/en/latest/?badge=latest)
6+
[![PyPI version](https://badge.fury.io/py/pylsp-rope.svg)](https://badge.fury.io/py/pylsp-rope)
57

6-
Extended refactoring capabilities for Python LSP Server using
7-
[Rope](https://github.com/python-rope/rope).
8+
Extended refactoring capabilities for Python LSP Server using [Rope](https://github.com/python-rope/rope).
89

9-
This is a plugin for [Python LSP
10-
Server](https://github.com/python-lsp/python-lsp-server), so you also need to
11-
have it installed.
10+
This is a plugin for [Python LSP Server](https://github.com/python-lsp/python-lsp-server), so you also need to have it installed.
1211

13-
python-lsp-server already has basic built-in support for using Rope, but it's
14-
currently limited to just renaming and completion. Installing this plugin adds
15-
more refactoring functionality to python-lsp-server.
16-
17-
## Installation
18-
19-
To use this plugin, you need to install this plugin in the same virtualenv as
20-
python-lsp-server itself.
21-
22-
``` bash
23-
pip install pylsp-rope
24-
```
25-
26-
Then run `pylsp` as usual, the plugin will be auto-discovered by
27-
python-lsp-server if you've installed it to the right environment. On Vim,
28-
refer to [Rope in Vim or
29-
Neovim](https://github.com/python-rope/rope/wiki/Rope-in-Vim-or-Neovim). For
30-
other editors, refer to your IDE/text editor's documentation on how to setup a
31-
language server.
12+
python-lsp-server already has basic built-in support for using Rope, but it's currently limited to just renaming and completion. Installing this plugin adds more refactoring functionality to python-lsp-server.
3213

3314
## Features
3415

35-
This plugin adds the following features to python-lsp-server:
36-
37-
Rename:
38-
39-
- implemented: variables, classes, functions (disabled by default)
40-
- coming soon: modules, packages (disabled by default)
41-
42-
Code Action:
43-
44-
- extract method
45-
- extract variable
46-
- inline method/variable/parameter
47-
- use function
48-
- method to method object
49-
- convert local variable to field
50-
- organize imports
51-
- introduce parameter
52-
- generate variable/function/class from undefined variable
53-
54-
Refer to [Rope documentation](https://github.com/python-rope/rope/blob/master/docs/overview.rst)
55-
for more details on how these refactoring works.
56-
57-
## Usage
58-
59-
### Rename
60-
61-
When Rename is triggered, rename the symbol under the cursor. If the symbol
62-
under the cursor points to a module/package, it will move that module/package
63-
files.
64-
65-
### Extract method
66-
67-
Variants:
68-
69-
- Extract method
70-
- Extract global method
71-
- Extract method including similar statements
72-
- Extract global method including similar statements
16+
- **Enhanced Rename**: Advanced cross-file renaming with Rope's refactoring engine
17+
- **Code Actions**: 12+ refactoring operations including extract method, inline, use function, and more
18+
- **Code Generation**: Create variables, functions, and classes from undefined symbols
19+
- **Import Organization**: Automatic cleanup and sorting of imports
20+
- **Local to Field**: Convert local variables to class attributes
7321

74-
When CodeAction is triggered and the cursor is on any block of code, extract
75-
that expression into a method. Optionally, similar statements can also be
76-
extracted.
22+
## Quick Start
7723

78-
### Extract variable
24+
### Installation
7925

80-
Variants:
26+
Install pylsp-rope in the same virtualenv as python-lsp-server:
8127

82-
- Extract variable
83-
- Extract global variable
84-
- Extract variable including similar statements
85-
- Extract global variable including similar statements
86-
87-
When CodeAction is triggered and the cursor is on a expression, extract that
88-
expression into a variable. Optionally, similar statements can also be
89-
extracted.
90-
91-
### Inline
92-
93-
When CodeAction is triggered and the cursor is on a resolvable Python variable,
94-
replace all calls to that method with the method body.
95-
96-
### Use function
97-
98-
When CodeAction is triggered and the cursor is on the function name of a `def`
99-
statement, try to replace code whose AST matches the selected function with a
100-
call to the function.
101-
102-
### Method to method object
103-
104-
When CodeAction is triggered and the cursor is on the function name of a `def`
105-
statement, create a callable class to replace that method. You may want to
106-
inline the method afterwards to remove the indirection.
107-
108-
### Convert local variable to field
109-
110-
When CodeAction is triggered wand the cursor is on a local variable inside a
111-
method, convert that local variable to an attribute.
112-
113-
### Organize import
114-
115-
Trigger CodeAction anywhere in a Python file to organize imports.
28+
```bash
29+
pip install pylsp-rope
30+
```
11631

117-
### Introduce parameter
32+
### Basic Configuration
11833

119-
When CodeAction is triggered and the cursor is selecting a Python variable or
120-
attribute, make that variable/attribute a parameter.
34+
Add to your LSP configuration:
12135

122-
### Generate code
36+
```json
37+
{
38+
"pylsp": {
39+
"plugins": {
40+
"pylsp_rope": {
41+
"enabled": true
42+
}
43+
}
44+
}
45+
}
46+
```
12347

124-
Variants:
48+
### Enable Rename Support
49+
50+
For advanced rename functionality, enable it explicitly:
51+
52+
```json
53+
{
54+
"pylsp": {
55+
"plugins": {
56+
"pylsp_rope": {
57+
"enabled": true,
58+
"rename": true
59+
}
60+
}
61+
}
62+
}
63+
```
12564

126-
- [x] Generate variable
127-
- [x] Generate function
128-
- [x] Generate class
129-
- [ ] Generate module
130-
- [ ] Generate package
65+
## Documentation
13166

132-
When CodeAction is triggered and the cursor is on an undefined Python
133-
variable, generate an empty variable/function/class/module/package for that
134-
name.
67+
Complete documentation is available at **[pylsp-rope.readthedocs.io](https://pylsp-rope.readthedocs.io/)**
13568

136-
## Configuration
69+
- **[Installation Guide](https://pylsp-rope.readthedocs.io/en/latest/installation.html)** - Setup for various editors
70+
- **[Configuration Guide](https://pylsp-rope.readthedocs.io/en/latest/configuration.html)** - Complete configuration options
71+
- **[Features Overview](https://pylsp-rope.readthedocs.io/en/latest/features.html)** - Detailed feature descriptions
72+
- **[Usage Examples](https://pylsp-rope.readthedocs.io/en/latest/usage.html)** - Practical examples
73+
- **[Troubleshooting](https://pylsp-rope.readthedocs.io/en/latest/troubleshooting.html)** - Common issues and solutions
13774

138-
You can enable rename support using pylsp-rope with workspace config key
139-
`pylsp.plugins.pylsp_rope.rename`.
75+
## Available Refactorings
14076

141-
Note that this differs from the config key `pylsp.plugins.rope_rename.enabled`
142-
that is used for the rope rename implementation using the python-lsp-rope's
143-
builtin `rope_rename` plugin. To avoid confusion, avoid enabling more than one
144-
python-lsp-server rename plugin. In other words, you should set both
145-
`pylsp.plugins.rope_rename.enabled = false` and `pylsp.plugins.jedi_rename.enabled = false`
146-
when pylsp-rope rename is enabled.
77+
| Category | Operations |
78+
|----------|------------|
79+
| **Extract** | Method, Variable (with similar statement support) |
80+
| **Inline** | Method, Variable, Parameter |
81+
| **Restructure** | Use Function, Method to Method Object, Local to Field |
82+
| **Generate** | Variable, Function, Class |
83+
| **Utilities** | Organize Imports, Introduce Parameter |
84+
| **Rename** | Enhanced cross-file renaming (Rope-based) |
14785

14886
## Caveat
14987

150-
Support for working on unsaved document is currently experimental, but it should work.
88+
Support for working on unsaved documents is currently experimental, but it should work.
15189

152-
This plugin is in early development, so expect some bugs. Please report in
153-
[Github issue tracker](https://github.com/python-lsp/python-lsp-server/issues)
154-
if you had any issues with the plugin.
90+
This plugin is in early development, so expect some bugs. Please report in the [GitHub issue tracker](https://github.com/python-lsp/python-lsp-server/issues) if you have any issues with the plugin.
15591

156-
## Developing
92+
## Contributing
15793

15894
See [CONTRIBUTING.md](https://github.com/python-rope/pylsp-rope/blob/main/CONTRIBUTING.md).
15995

16096
## Packaging status
16197

16298
[![Packaging status](https://repology.org/badge/vertical-allrepos/python:pylsp-rope.svg)](https://repology.org/project/python:pylsp-rope/versions)
16399

164-
[![Packaging status](https://repology.org/badge/vertical-allrepos/python:lsp-rope.svg)](https://repology.org/project/python:lsp-rope/versions)
165-
166100
## Credits
167101

168-
This package was created with
169-
[Cookiecutter](https://github.com/audreyr/cookiecutter) from
170-
[python-lsp/cookiecutter-pylsp-plugin](https://github.com/python-lsp/cookiecutter-pylsp-plugin)
171-
project template.
102+
This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) from [python-lsp/cookiecutter-pylsp-plugin](https://github.com/python-lsp/cookiecutter-pylsp-plugin) project template.

‎doc/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/*

‎doc/conf.py‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Sphinx configuration file
2+
3+
import os
4+
import sys
5+
6+
# Add project root to Python path for autodoc
7+
sys.path.insert(0, os.path.abspath(".."))
8+
9+
# -- Project information --
10+
project = "pylsp-rope"
11+
copyright = "2024, pylsp-rope contributors"
12+
author = "pylsp-rope contributors"
13+
release = "0.1.4"
14+
15+
# -- General configuration --
16+
extensions = [
17+
"myst_parser", # Markdown support
18+
"sphinx.ext.autodoc",
19+
"sphinx.ext.viewcode",
20+
"sphinx.ext.napoleon",
21+
]
22+
23+
# MyST parser configuration
24+
myst_enable_extensions = [
25+
"colon_fence",
26+
"deflist",
27+
"html_admonition",
28+
"linkify",
29+
"replacements",
30+
"smartquotes",
31+
"substitution",
32+
"tasklist",
33+
]
34+
35+
# -- Options for HTML output --
36+
html_theme = "sphinx_rtd_theme"
37+
html_static_path = []
38+
html_theme_options = {
39+
"canonical_url": "",
40+
"analytics_id": "",
41+
"logo_only": False,
42+
"prev_next_buttons_location": "bottom",
43+
"style_external_links": False,
44+
"collapse_navigation": True,
45+
"sticky_navigation": True,
46+
"navigation_depth": 4,
47+
"includehidden": True,
48+
"titles_only": False,
49+
}
50+
51+
# -- Master document --
52+
master_doc = "index"
53+
54+
# -- Exclude patterns --
55+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
56+
57+
# -- Options for other output formats --
58+
htmlhelp_basename = "pylsp-ropedoc"
59+
latex_documents = [
60+
(
61+
master_doc,
62+
"pylsp-rope.tex",
63+
"pylsp-rope Documentation",
64+
"pylsp-rope contributors",
65+
"manual",
66+
),
67+
]
68+
69+
man_pages = [(master_doc, "pylsp-rope", "pylsp-rope Documentation", [author], 1)]
70+
71+
texinfo_documents = [
72+
(
73+
master_doc,
74+
"pylsp-rope",
75+
"pylsp-rope Documentation",
76+
author,
77+
"pylsp-rope",
78+
"One line description of project.",
79+
"Miscellaneous",
80+
),
81+
]
82+
83+
# -- Exclude patterns --
84+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
85+
86+
# -- ReadTheDocs specific configuration --
87+
# When building on ReadTheDocs, these environment variables are available
88+
if os.environ.get("READTHEDOCS") == "True":
89+
html_theme = "sphinx_rtd_theme"

0 commit comments

Comments
 (0)