diff --git a/CHANGELOG_CODE.md b/CHANGELOG_CODE.md
index 4e1e6de..0b6a4be 100644
--- a/CHANGELOG_CODE.md
+++ b/CHANGELOG_CODE.md
@@ -19,7 +19,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1].
### Changed
-* [The documentation][60-2] is updated. (fcf2c0fb, 91d467ac)
+* [The documentation][60-2] is updated. (fcf2c0fb, 91d467ac, HEAD)
* [`PyrightBundle`][60-3] and [`PyrightIcon`][60-4] are renamed. (7032faff)
* Gradle is updated to 8.9. (2397aafd, c5d7c8c8)
* [Kotlin Serialization Gradle Plugin][60-5] is updated to 1.7.1.
@@ -27,7 +27,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1].
* [Kover Gradle Plugin][60-6] is updated to 0.8.2. (eb306695, 87e5660a)
* [The `lsp4ij` submodule][60-7] is added. (b67210b7)
* Various files are moved to [the new `cli` submodule][60-8]. (37136d65)
-* Path-hints-related logic is revisited to use `PropertyGraph`. (HEAD)
+* Path-hints-related logic is revisited to use `PropertyGraph`. (bf2de95e)
### Fixed
@@ -37,7 +37,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1].
[60-1]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/4ca4b746/src/main/kotlin/com/insyncwithfoo/pyright/actions/CopyFileCommand.kt
- [60-2]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/91d467ac/docs
+ [60-2]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/HEAD/docs
[60-3]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/7032faff/src/main/kotlin/com/insyncwithfoo/pyright/Bundle.kt
[60-4]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/7032faff/src/main/kotlin/com/insyncwithfoo/pyright/Icon.kt
[60-5]: https://github.com/Kotlin/kotlinx.serialization
diff --git a/README.md b/README.md
index 6dd9c68..664440d 100644
--- a/README.md
+++ b/README.md
@@ -6,27 +6,23 @@
[![Rating](https://img.shields.io/jetbrains/plugin/r/rating/24145)][7]
[![Downloads](https://img.shields.io/jetbrains/plugin/d/24145)][8]
-![](docs/assets/cli-demo-2.png)
+![](./docs/assets/demo.png)
Pyright integration for PyCharm.
This plugin runs [the Pyright type checker][1] on-the-fly
-as you edit your Python files.
+and reroutes its diagnostics back to the IDE as you code.
-It works by saving all your files as-is before running
-the executable provided by you. If you are not OK with that,
-please do not install this plugin.
-
-Note: If you use PyCharm Professional,
-install [the Pyright Language Server plugin][2] instead.
+Warning: Depending on the running mode,
+it might save your files at very fast pace.
## Usage
Go to Settings | Tools |
Pyright (Global) / Pyright (Project)
-and set the path to your Pyright executable.
+and set the path to your Pyright executable(s).
(Not sure what this means? See [the docs][3] for more information.)
@@ -36,7 +32,7 @@ You should see the annotations in a few seconds.
[1]: https://github.com/microsoft/pyright
[2]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm
- [3]: https://insyncwithfoo.github.io/pyright-for-pycharm/configurations/common/#executable
+ [3]: https://insyncwithfoo.github.io/pyright-for-pycharm/configurations/running-modes/
diff --git a/docs/assets/cli-demo-1.png b/docs/assets/cli-demo-1.png
deleted file mode 100644
index bdcb1fc..0000000
Binary files a/docs/assets/cli-demo-1.png and /dev/null differ
diff --git a/docs/assets/cli-global-configuration-panel.png b/docs/assets/cli-global-configuration-panel.png
deleted file mode 100644
index 51fda94..0000000
Binary files a/docs/assets/cli-global-configuration-panel.png and /dev/null differ
diff --git a/docs/assets/cli-project-configuration-panel.png b/docs/assets/cli-project-configuration-panel.png
deleted file mode 100644
index bf5cfa5..0000000
Binary files a/docs/assets/cli-project-configuration-panel.png and /dev/null differ
diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-error.png b/docs/assets/configurations-demo-others-minimum-severity-level-error.png
similarity index 100%
rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-error.png
rename to docs/assets/configurations-demo-others-minimum-severity-level-error.png
diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-information.png b/docs/assets/configurations-demo-others-minimum-severity-level-information.png
similarity index 100%
rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-information.png
rename to docs/assets/configurations-demo-others-minimum-severity-level-information.png
diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-warning.png b/docs/assets/configurations-demo-others-minimum-severity-level-warning.png
similarity index 100%
rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-warning.png
rename to docs/assets/configurations-demo-others-minimum-severity-level-warning.png
diff --git a/docs/assets/configurations-global-panel.png b/docs/assets/configurations-global-panel.png
new file mode 100644
index 0000000..10f9ad2
Binary files /dev/null and b/docs/assets/configurations-global-panel.png differ
diff --git a/docs/assets/configurations-project-panel.png b/docs/assets/configurations-project-panel.png
new file mode 100644
index 0000000..61a23a6
Binary files /dev/null and b/docs/assets/configurations-project-panel.png differ
diff --git a/docs/assets/cli-demo-2.png b/docs/assets/demo.png
similarity index 100%
rename from docs/assets/cli-demo-2.png
rename to docs/assets/demo.png
diff --git a/docs/assets/cli-features-demo-auto-suggest-executable.png b/docs/assets/features-demo-auto-suggest-executable.png
similarity index 100%
rename from docs/assets/cli-features-demo-auto-suggest-executable.png
rename to docs/assets/features-demo-auto-suggest-executable.png
diff --git a/docs/assets/icon-outline-10.svg b/docs/assets/icon-outline-10.svg
deleted file mode 120000
index c257c8c..0000000
--- a/docs/assets/icon-outline-10.svg
+++ /dev/null
@@ -1 +0,0 @@
-../../src/main/resources/icons/outline-bold-black.svg
\ No newline at end of file
diff --git a/docs/assets/icon-outline-5-white.svg b/docs/assets/icon-outline-5-white.svg
deleted file mode 120000
index 3b92e76..0000000
--- a/docs/assets/icon-outline-5-white.svg
+++ /dev/null
@@ -1 +0,0 @@
-../../src/main/resources/icons/outline-thin-white.svg
\ No newline at end of file
diff --git a/docs/assets/icon-outline-5.svg b/docs/assets/icon-outline-5.svg
deleted file mode 120000
index 262ec41..0000000
--- a/docs/assets/icon-outline-5.svg
+++ /dev/null
@@ -1 +0,0 @@
-../../src/main/resources/icons/outline-thin-black.svg
\ No newline at end of file
diff --git a/docs/assets/icon-outline-10-white.svg b/docs/assets/icon-outline.svg
similarity index 100%
rename from docs/assets/icon-outline-10-white.svg
rename to docs/assets/icon-outline.svg
diff --git a/docs/assets/inspection-highlight-severity-levels.png b/docs/assets/inspection-highlight-severity-levels.png
index 9bff07a..4abfc4a 100644
Binary files a/docs/assets/inspection-highlight-severity-levels.png and b/docs/assets/inspection-highlight-severity-levels.png differ
diff --git a/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png b/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png
deleted file mode 100644
index 1b84881..0000000
Binary files a/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png
deleted file mode 100644
index 22273fe..0000000
Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png
deleted file mode 100644
index 05c2610..0000000
Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png
deleted file mode 100644
index 430061a..0000000
Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-completion-support-disabled.png b/docs/assets/lsp-configurations-demo-completion-support-disabled.png
deleted file mode 100644
index 1bc96e7..0000000
Binary files a/docs/assets/lsp-configurations-demo-completion-support-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-completion-support-enabled.png b/docs/assets/lsp-configurations-demo-completion-support-enabled.png
deleted file mode 100644
index b35d857..0000000
Binary files a/docs/assets/lsp-configurations-demo-completion-support-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png b/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png
deleted file mode 100644
index 15aa347..0000000
Binary files a/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png b/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png
deleted file mode 100644
index d3e2cef..0000000
Binary files a/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-hover-support-disabled.png b/docs/assets/lsp-configurations-demo-hover-support-disabled.png
deleted file mode 100644
index 5d66226..0000000
Binary files a/docs/assets/lsp-configurations-demo-hover-support-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-hover-support-enabled.png b/docs/assets/lsp-configurations-demo-hover-support-enabled.png
deleted file mode 100644
index e3e3f71..0000000
Binary files a/docs/assets/lsp-configurations-demo-hover-support-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png
deleted file mode 100644
index 6c0e220..0000000
Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png
deleted file mode 100644
index 1fd64c7..0000000
Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png
deleted file mode 100644
index a4cf9ba..0000000
Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png
deleted file mode 100644
index c027ef8..0000000
Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png
deleted file mode 100644
index e0849ab..0000000
Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png b/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png
deleted file mode 100644
index 3cbab75..0000000
Binary files a/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png b/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png
deleted file mode 100644
index 7a834bd..0000000
Binary files a/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png and /dev/null differ
diff --git a/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png b/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png
deleted file mode 100644
index be99018..0000000
Binary files a/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png and /dev/null differ
diff --git a/docs/assets/lsp-demo-1.png b/docs/assets/lsp-demo-1.png
deleted file mode 100644
index c2629c0..0000000
Binary files a/docs/assets/lsp-demo-1.png and /dev/null differ
diff --git a/docs/assets/lsp-features-demo-auto-suggest-executable.png b/docs/assets/lsp-features-demo-auto-suggest-executable.png
deleted file mode 100644
index 8bba17b..0000000
Binary files a/docs/assets/lsp-features-demo-auto-suggest-executable.png and /dev/null differ
diff --git a/docs/assets/lsp-global-configuration-panel.png b/docs/assets/lsp-global-configuration-panel.png
deleted file mode 100644
index b1fb293..0000000
Binary files a/docs/assets/lsp-global-configuration-panel.png and /dev/null differ
diff --git a/docs/assets/lsp-project-configuration-panel.png b/docs/assets/lsp-project-configuration-panel.png
deleted file mode 100644
index 4de6aa4..0000000
Binary files a/docs/assets/lsp-project-configuration-panel.png and /dev/null differ
diff --git a/docs/assets/lsp-restart-server-button.png b/docs/assets/lsp-restart-server-button.png
deleted file mode 100644
index 88de29c..0000000
Binary files a/docs/assets/lsp-restart-server-button.png and /dev/null differ
diff --git a/docs/assets/lsp4ij-restart-server-button.png b/docs/assets/lsp4ij-restart-server-button.png
new file mode 100644
index 0000000..e6a5f26
Binary files /dev/null and b/docs/assets/lsp4ij-restart-server-button.png differ
diff --git a/docs/assets/lsp4ij-stop-server-button.png b/docs/assets/lsp4ij-stop-server-button.png
new file mode 100644
index 0000000..3418e88
Binary files /dev/null and b/docs/assets/lsp4ij-stop-server-button.png differ
diff --git a/docs/configurations/cli.md b/docs/configurations/cli.md
deleted file mode 100644
index e7d8fb4..0000000
--- a/docs/configurations/cli.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# CLI-specific configurations
-
-
-## Configuration file
-
-!!! note
-
- This configuration is [deliberately][1] unsupported by LSP.
- The language server will search for the configuration file(s)
- inside the root directory of the workspace.
-
-Despite being called "file", this can be a path to a directory
-containing a `pyrightconfig.json` and/or a `pyproject.toml`
-(the former takes precedence if both are present).
-This path will be passed to the executable via [the `--project` option][2].
-
-* If the executable is local, only the local path is used.
-* If the executable is global, the local path is used if it is specified,
- falling back to the global one.
-
-If the path retrieved using the aforementioned strategy is not specified,
-the project directory is used.
-
-
-## Process timeout
-
-Modify this option to set a maximum limit (in milliseconds)
-each process should take before it is forcibly destroyed.
-
-A value of -1 disables the timeout.
-
-Default: 10 seconds.
-
-!!! warning
-
- If there is no time limit, the process might run indefinitely,
- leading to undesired CPU and RAM usage.
-
-
-## Number of threads
-
-Modify this option to paralellize type checking
-on up to the specified number of threads.
-A value of 0 means nothing is passed to the executable.
-
-This corresponds to the `--threads` option.
-
-Default: 0
-
-!!! warning
-
- The `--thread` option is only available in Pyright 1.1.371 and later.
- Modifying it will cause an error for older versions.
-
-
-## Minimum severity level
-
-Modify this option to set a minimum threshold that
-only the diagnostics whose severity is equal or higher than it
-will be emitted.
-
-This corresponds to the `--level` option.
-
-Default: Information
-
-=== "Information"
-
- ![](../assets/cli-configurations-demo-others-minimum-severity-level-information.png)
-
-=== "Warning"
-
- ![](../assets/cli-configurations-demo-others-minimum-severity-level-warning.png)
-
-=== "Error"
-
- ![](../assets/cli-configurations-demo-others-minimum-severity-level-error.png)
-
-
- [1]: https://github.com/microsoft/pyright/discussions/7650
- [2]: https://microsoft.github.io/pyright/#/command-line
diff --git a/docs/configurations/common.md b/docs/configurations/common.md
deleted file mode 100644
index 2ae5f1e..0000000
--- a/docs/configurations/common.md
+++ /dev/null
@@ -1,191 +0,0 @@
-# Common configurations
-
-
-## Executable
-
-For CLI/LSP to work, at least one executable file needs to be defined
-using either the Global or Project panel.
-
-!!! question "[How do I install the executables?][1]"
-
-Such a file is typically named `pyright`/`pyright-python` (CLI)
-or `pyright-langserver`/`pyright-python-langserver` (LSP)
-and can likely be found in:
-
-!!! note
-
- The locations mentioned here are for Pip and NPM-like managers.
- For other tools (e.g. Homebrew), see their documentation
- to know where they store their executable files.
-
-| Manager | Type | OS | Directory |
-|:--------|:-------|:--------|:---------------------------------------------------|
-| NPM | Global | Windows | `%APPDATA%\npm` |
-| NPM | Global | Linux | `/usr/local/bin` |
-| Pip | Global | Windows | `%LOCALAPPDATA%\Programs\Python\\Scripts` |
-| Pip | Global | Linux | `~/.local/bin` |
-| NPM | Local | Windows | `.\node_modules\.bin` |
-| NPM | Local | Linux | `./node_modules/.bin` |
-| Pip | Local | Windows | `.\\Scripts` |
-| Pip | Local | Linux | `.//bin` |
-
-??? question "What's the difference between these files?"
-
- [TLDR][2]: Some may output "unexpected" things.
-
-!!! note
-
- For LSP to work with a WSL project,
- its interpreter and the executable must be
- located within the same distribution.
-
-If the executables can't be found in the aforementioned locations,
-see the following pages for more information:
-
-* [Where does npm install packages?][3] - Stack Overflow
-* [Where does pip install its packages?][4] - Stack Overflow
-* [folders][5] - npm Docs
-
-You can also use a relative path.
-It would be interpreted as relative to the project directory.
-
-The executable is used as-is with no additional checks,
-so CLI/LSP will still work even if, for example,
-it's a wrapper script that outputs diagnostics in the expected format.
-
-!!! tip
-
- For the best experience, always use or maintain compatibility
- with the latest version of Pyright.
-
-
-### Always use global
-
-Check this option to always use the global executable
-and configuration file.
-
-Default: `false`
-
-
-### Auto-suggest executable
-
-Check this option to automatically find and
-suggest an executable for the current project on open.
-See [the corresponding feature][6] for more information.
-
-Default: `true`
-
-
-## Tooltips
-
-These options are not applied retroactively;
-you need to make an edit to see the effect.
-
-
-### Use editor font
-
-Check this option to display tooltips in the editor font.
-
-Default: `false`
-
-=== "Enabled"
-
- ![](../assets/configurations-demo-tooltips-use-editor-font.png)
-
-=== "Disabled"
-
- ![](../assets/configurations-demo-tooltips-default.png)
-
-
-### Add prefix
-
-Check this option to prefix tooltips with "Pyright:".
-
-Default: `false`
-
-=== "Enabled"
-
- ![](../assets/configurations-demo-tooltips-add-tooltip-prefix.png)
-
-=== "Disabled"
-
- ![](../assets/configurations-demo-tooltips-default.png)
-
-
-## Highlight severity levels
-
-Pyright diagnostics have [three possible levels][7]:
-Error, warning, and information.
-These can be mapped to different highlight severity levels in the IDE.
-
-!!! note
-
- The language server may also output "hint" diagnostics
- that report code as ["unnecessary" or "deprecated"][8].
- These can be [disabled][9] from the global configuration panel.
-
-
-### Configuring
-
-The target levels can be configured by modifying the options provided
-at Editor | Inspections -->
-Pyright diagnostics / Pyright language server diagnostics.
-
-!!! note ""
-
- Only the levels defined in the select boxes
- under the Options pane are honored.
-
-![](../assets/inspection-highlight-severity-levels.png)
-
-For each diagnostic level, there are four highlight levels to choose from:
-
-| Level | Default effects |
-|--------------|-----------------------|
-| Error | Red squiggles |
-| Warning | Yellow squiggles |
-| Weak warning | Dark yellow squiggles |
-| Information | No visible effects |
-
-!!! info ""
-
- These levels are semantic, not visual.
-
-The Information level is the only one not considered
-"problematic" by the IDE. Annotations of this kind
-will not be reported as "problems" during batch inspections
-(File, Project Errors and similar tabs in
-the Problems tool window).
-
-!!! note
-
- Despite having no visible effects,
- Information annotations are still shown on hover.
-
- === "Information"
-
- ![](../assets/inspection-information-demo.png)
-
- === "Weak warning"
-
- ![](../assets/inspection-weak-warning-demo.png)
-
-
-### Recommended levels
-
-| Diagnostic | For most users (default) | For lax users |
-|-------------|--------------------------|---------------|
-| Error | Error | Warning |
-| Warning | Warning | Weak warning |
-| Information | Weak warning | Weak warning |
-
-
- [1]: ../how-to.md#how-to-install-the-pyright-executables
- [2]: ../faq.md#whats-the-difference-between-the-pyright-and-pyright-python-files
- [3]: https://stackoverflow.com/q/5926672
- [4]: https://stackoverflow.com/q/29980798
- [5]: https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables
- [6]: ../features.md#executable-suggestion
- [7]: https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings
- [8]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticTag
- [9]: lsp.md#tagged-hints
diff --git a/docs/configurations/executables.md b/docs/configurations/executables.md
new file mode 100644
index 0000000..07cab4d
--- /dev/null
+++ b/docs/configurations/executables.md
@@ -0,0 +1,110 @@
+## Executable and language server executable
+
+The `pyright` (or `pyright-python`) and
+`pyright-langserver` (or `pyright-python-langserver`) files
+can be found in the following locations:
+
+!!! question "[What are these executables used for?][1]"
+
+!!! question "[How do I install the executables?][2]"
+
+!!! question "[What's the difference between these files?][3]"
+
+!!! note
+
+ The locations mentioned here are for Pip and NPM-like managers.
+ For other tools (e.g. Homebrew), see their documentation
+ to know where they store their executable files.
+
+| Manager | Type | OS | Directory |
+|:--------|:-------|:--------|:---------------------------------------------------|
+| NPM | Global | Windows | `%APPDATA%\npm` |
+| NPM | Global | Linux | `/usr/local/bin` |
+| Pip | Global | Windows | `%LOCALAPPDATA%\Programs\Python\\Scripts` |
+| Pip | Global | Linux | `~/.local/bin` |
+| NPM | Local | Windows | `.\node_modules\.bin` |
+| NPM | Local | Linux | `./node_modules/.bin` |
+| Pip | Local | Windows | `.\\Scripts` |
+| Pip | Local | Linux | `.//bin` |
+
+If the executables can't be found in the aforementioned locations,
+see the following pages for more information:
+
+* [Where does npm install packages?][4] - Stack Overflow
+* [Where does pip install its packages?][5] - Stack Overflow
+* [folders][6] - npm Docs
+
+If a relative path is specified, it would be interpreted
+as relative to the project directory.
+
+The executables are used as-is with no additional checks.
+This is useful if you want to use a Pyright fork or a custom script.
+
+!!! tip
+
+ For the best experience, always use or maintain compatibility
+ with the latest version of Pyright.
+
+
+### Configuration files
+
+| Used by running mode(s) | Default | Corresponding CLI option |
+|-------------------------|--------------------------|--------------------------|
+| Command line | Project's root directory | `--project` |
+
+Despite being called "file", this can be a path to a directory
+containing a `pyrightconfig.json` and/or a `pyproject.toml`
+(the former takes precedence if both are present).
+
+* If a local executable is specified, the local path is used.
+* If only the global executable is specified, the local path is used.
+* If no local configuration file is specified, the global is used.
+
+If the path retrieved using the aforementioned strategy is not specified,
+the project's root directory is used.
+
+!!! note
+
+ This configuration is [deliberately][7] unsupported by LSP.
+ The language server will search for the configuration file(s)
+ inside the root directory of the workspace.
+
+
+### Always use global
+
+| Used by running mode(s) | Default |
+|-------------------------|---------|
+| N/A | `false` |
+
+Enable this setting to always use
+the global executables and configuration file.
+
+
+### Auto-suggest executable
+
+| Used by running mode(s) | Default |
+|-------------------------|---------|
+| N/A | `true` |
+
+Enable this setting to automatically find and
+suggest an executable for the current project on open.
+See [the corresponding feature][8] for more information.
+
+
+### UI hints
+
+As a path field is edited, the small hint under the field
+will show whether the path is valid or invalid.
+
+This is only used to give a general hint;
+a path can still be saved even if it is marked as invalid.
+
+
+ [1]: running-modes.md
+ [2]: ../how-to.md#how-to-install-the-pyright-executables
+ [3]: ../faq.md#whats-the-difference-between-the-pyright-and-pyright-python-files
+ [4]: https://stackoverflow.com/q/5926672
+ [5]: https://stackoverflow.com/q/29980798
+ [6]: https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables
+ [7]: https://github.com/microsoft/pyright/discussions/7650
+ [8]: ../features.md#executable-suggestion
diff --git a/docs/configurations/index.md b/docs/configurations/index.md
new file mode 100644
index 0000000..d33f250
--- /dev/null
+++ b/docs/configurations/index.md
@@ -0,0 +1,19 @@
+# Configurations
+
+The plugin provides two configuration panels:
+
+* Pyright (Global) for application-level settings, and
+* Pyright (Project) for project-level settings.
+
+They can be found under the Tools section of the Settings panel.
+
+For the plugin to work, at least one [executable][1] needs to be specified.
+Note that different [running modes][2] require different executables.
+
+To configure highlight severity levels,
+use [the inspection entry][3]'s corresponding pane.
+
+
+ [1]: executables.md
+ [2]: running-modes.md
+ [3]: inspection.md
diff --git a/docs/configurations/inspection.md b/docs/configurations/inspection.md
new file mode 100644
index 0000000..824fd48
--- /dev/null
+++ b/docs/configurations/inspection.md
@@ -0,0 +1,58 @@
+## Inspection entry
+
+This plugin can be disabled by disabling
+the inspection Pyright diagnostics,
+which can be found under Editor | Inspections.
+However, this is not recommended for other purposes than debugging.
+
+
+### Highlight severity levels
+
+Pyright diagnostics have [three possible levels][1]:
+Error, warning, and information.
+These can be mapped to different highlight severity levels in the IDE.
+
+The target levels can be configured via
+the inspection's corresponding settings pane.
+
+!!! note ""
+
+ Only the levels defined in the dropdowns
+ under the Options pane are honored.
+
+![](../assets/inspection-highlight-severity-levels.png)
+
+!!! info ""
+
+ These levels are semantical, not visual.
+
+The Information level is the only one not considered
+"problematic" by the IDE. Annotations of this kind
+will not be reported as "problems" during batch inspections
+(File, Project Errors and similar tabs in
+the Problems tool window).
+
+!!! note
+
+ Despite having no visible effects,
+ Information annotations are still shown on hover.
+
+ === "Information"
+
+ ![](../assets/inspection-information-demo.png)
+
+ === "Weak warning"
+
+ ![](../assets/inspection-weak-warning-demo.png)
+
+
+#### Recommended levels
+
+| Diagnostic | For most users (default) | For lax users |
+|-------------|--------------------------|---------------|
+| Error | Error | Warning |
+| Warning | Warning | Weak warning |
+| Information | Weak warning | Weak warning |
+
+
+ [1]: https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings
diff --git a/docs/configurations/lsp.md b/docs/configurations/lsp.md
deleted file mode 100644
index 1e5252a..0000000
--- a/docs/configurations/lsp.md
+++ /dev/null
@@ -1,315 +0,0 @@
-# LSP-specific configurations
-
-
-## Tooltips
-
-These options are not applied retroactively;
-you need to make an edit to see the effect.
-
-
-### Link error codes
-
-Enable this option to display error codes as links.
-
-Default: `false`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-tooltips-link-error-codes.png)
-
-=== "Disabled"
-
- ![](../assets/configurations-demo-tooltips-default.png)
-
-
-## Language server settings
-
-These settings are not applied retroactively;
-the server needs to be [restarted][1] for them to have effects.
-
-
-### Auto-restart server
-
-Check this option to automatically restart
-the language server on configuration change.
-
-[Highlight severity level settings][2]
-will not trigger this behaviour.
-
-Default: `false`
-
-!!! note
-
- The server might be restarted more than once if
- both configuration panels are modified.
-
-
-### Completion support
-
-Check this option to enable completion support.
-
-Default: `false`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-completion-support-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-completion-support-disabled.png)
-
-!!! note
-
- The autocompletion result might not precisely
- follow the server's response due to
- a few custom modifications employed by the plugin
- to monkeypatch IDE bugs (e.g. [IJPL-155741][3]).
-
-
-### Diagnostics support
-
-Uncheck this option to disable diagnostics support.
-
-Default: `true`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-diagnostics-support-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-diagnostics-support-disabled.png)
-
-
-### Go-to-definition support
-
-Check this option to enable go-to-definition support.
-
-Default: `false`
-
-!!! note
-
- As of yet, PyCharm's native support is
- prioritized over the language server's.
-
- This means Ctrl B (or similar shortcuts)
- will only trigger PyCharm's support on tokens it can handle
- (that is, most of them).
-
- The difference between the set of all tokens which Pyright support
- and that of PyCharm is currently unknown.
-
- See [this issue][4] for more information.
-
-
-### Hover support
-
-Uncheck this option to disable hover support.
-
-Default: `true`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-hover-support-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-hover-support-disabled.png)
-
-
-### Autocomplete parentheses
-
-Check this option to also automatically insert parentheses
-for function, method and constructor completions.
-
-Default: `false`
-
-=== "Before"
-
- ![](../assets/lsp-configurations-demo-autocomplete-parentheses-before.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png)
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png)
-
-
-### Auto-import completions
-
-Uncheck this option to prevent the language server from offering
-completions which, if accepted, will also add a `import` statement
-for that newly introduced symbol.
-
-This corresponds to the `python.analysis.autoImportCompletions` setting.
-
-Default: `true`
-
-=== "Auto-import completions enabled"
-
- ![](../assets/lsp-configurations-demo-completion-support-enabled.png)
-
-=== "Auto-import completions disabled"
-
- ![](../assets/lsp-configurations-demo-auto-import-completions-disabled.png)
-
-=== "Completion support disabled"
-
- ![](../assets/lsp-configurations-demo-completion-support-disabled.png)
-
-
-### Add common search paths
-
-Uncheck this option to tell the language server not to add
-common search paths like `src` when there are
-no execution environments defined in the configuration file.
-
-This corresponds to the `python.analysis.autoSearchPaths` setting.
-
-Default: `true`
-
-
-### Diagnostic mode
-
-!!! note
-
- This option's usefulness is as of yet unknown.
-
-Modify this option to control the number of files
-for which the language server will analyze and report diagnostics.
-
-This corresponds to the `python.analysis.diagnosticMode` setting.
-
-Default: *Open files only*
-
-
-### Log level
-
-!!! note
-
- Language server logs are not recorded in `idea.log` by default.
- You need to manually [enable it][5].
-
-Modify this option to make the language server
-emit more or less [log messages][6].
-
-This corresponds to the `python.analysis.logLevel` setting.
-
-Default: Information
-
-
-### Monkeypatch auto-import details
-
-Uncheck this option to prevent the original completion item detail
-("Auto-import" or a similar localized message)
-from being overridden by its import source.
-
-Default: `true`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png)
-
-
-### Monkeypatch trailing quote bug
-
-Uncheck this option to use the IDE's native implementation
-when applying quoted completions,
-which may insert extraneous trailing quotes.
-
-Upstream issue: [IJPL-155741][7].
-
-Default: `true`
-
-=== "Before"
-
- ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png)
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png)
-
-
-### Tagged hints
-
-Uncheck this option to prevent the language server from emitting
-"Unnecessary" and "Deprecated" hints, which are visualized in the IDE
-as faded-out and strikethrough text, correspondingly.
-
-This corresponds to the `pyright.disableTaggedHints` setting.
-
-Default: `true`
-
-=== "Enabled"
-
- ![](../assets/lsp-configurations-demo-tagged-hints-enabled.png)
-
-=== "Disabled"
-
- ![](../assets/lsp-configurations-demo-tagged-hints-disabled.png)
-
-
-### Targeted file extensions
-
-A file whose extension is included in this list will be recognized
-as suitable for the language server to run on.
-This is useful if you use a server
-whose support range is wider than that of Pyright.
-
-Each extension should be written on one line when the editor is expanded.
-Otherwise, use the pipe character (`|`) to separate them.
-
-Leading and trailing whitespace are stripped away.
-Blank extensions are thus considered invalid.
-
-Default: `py`, `pyi`
-
-!!! note
-
- Presumably, due to a limitation/bug of IntelliJ,
- characters like "🔥" (U+1F525 Fire, the extension for [Mojo][8])
- cannot be serialized correctly into setting files
- and therefore will not persist between IDE sessions.
-
- Testing shows that this affects characters
- whose codepoints are greater than U+FFFD.
-
-
-### Workspace folders
-
-The folders defined by this option will be passed
-to the language server as "[workspace folders][9]".
-Pyright will only recognize `pyproject.toml`/`pyrightconfig.json` files
-which are direct children of these folders.
-
-Possible choices:
-
-* Project base directories:
- Top-level directories which contain files related to the project,
- often only one (project root).
-* Source roots:
- Directories marked as "[source roots][10]".
-
-Default: Project base directories
-
-
- [1]: ../how-to.md#how-to-restart-the-language-server
- [2]: ./common.md#highlight-severity-levels
- [3]: https://youtrack.jetbrains.com/issue/IJPL-155741
- [4]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm/issues/29
- [5]: ../how-to.md#how-to-enable-language-server-logging
- [6]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_logMessage
- [7]: https://youtrack.jetbrains.com/issue/IJPL-155741
- [8]: https://en.wikipedia.org/wiki/Mojo_(programming_language)
- [9]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_workspaceFolders
- [10]: https://www.jetbrains.com/help/pycharm/content-root.html
diff --git a/docs/configurations/other.md b/docs/configurations/other.md
new file mode 100644
index 0000000..020bd80
--- /dev/null
+++ b/docs/configurations/other.md
@@ -0,0 +1,101 @@
+# Other settings
+
+
+## Tooltip settings
+
+These options are not applied retroactively;
+you need to make an edit to see the effect.
+
+
+### Use editor font
+
+| Used by running mode(s) | Default |
+|-------------------------|---------|
+| Command line | `false` |
+
+Enable this setting to display tooltips in the editor font.
+
+=== "Enabled"
+
+ ![](../assets/configurations-demo-tooltips-use-editor-font.png)
+
+=== "Disabled"
+
+ ![](../assets/configurations-demo-tooltips-default.png)
+
+
+### Add prefix
+
+| Used by running mode(s) | Default |
+|-------------------------|---------|
+| Command line | `false` |
+
+Enable this setting to prefix tooltips with "Pyright:".
+
+=== "Enabled"
+
+ ![](../assets/configurations-demo-tooltips-add-tooltip-prefix.png)
+
+=== "Disabled"
+
+ ![](../assets/configurations-demo-tooltips-default.png)
+
+
+## Command-line-mode-specific settings
+
+
+### Process timeout
+
+| Default | Corresponding CLI option |
+|-------------------|--------------------------|
+| 10 seconds | N/A |
+
+Modify this setting to set a maximum limit (in milliseconds)
+each process should take before it is forcibly destroyed.
+
+A value of -1 disables the timeout.
+
+!!! warning
+
+ If there is no time limit, the process might run indefinitely
+ in cases of bugs, leading to undesired CPU and RAM usage.
+
+
+### Number of threads
+
+| Default | Corresponding CLI option |
+|----------|--------------------------|
+| 0 | `--threads` |
+
+Modify this setting to paralellize type checking
+on up to the specified number of threads.
+
+A value of 0 means nothing is passed to the executable.
+
+!!! warning
+
+ The `--thread` option is only available in Pyright 1.1.371 and later.
+ Modifying it will cause an error for older versions.
+
+
+## Minimum severity level
+
+| Default | Corresponding CLI option |
+|--------------------|--------------------------|
+| Information | `--level` |
+
+Modify this setting to set a minimum threshold that
+only diagnostics whose severity is equal or higher than it
+will be emitted.
+
+=== "Information"
+
+ ![](../assets/configurations-demo-others-minimum-severity-level-information.png)
+
+=== "Warning"
+
+ ![](../assets/configurations-demo-others-minimum-severity-level-warning.png)
+
+=== "Error"
+
+ ![](../assets/configurations-demo-others-minimum-severity-level-error.png)
diff --git a/docs/configurations/related.md b/docs/configurations/related.md
deleted file mode 100644
index 813ba77..0000000
--- a/docs/configurations/related.md
+++ /dev/null
@@ -1,26 +0,0 @@
-## UI hints
-
-As a path field is edited, the small hint under the field
-will show whether the path is valid or invalid.
-
-This is only used to give a general hint;
-a path can still be saved even if it is marked as invalid.
-
-
-## Inspections
-
-The inspections shown in the [Highlight severity levels][1] section
-can be disabled, though this is not recommended.
-The effect of doing so is different for each plugin.
-
-* For CLI:
- * The executable will not be executed.
- * Files will not be automatically saved.
-
-* For LSP:
- * New sessions will not be started.
- * Existing sessions will stop on [restart][2].
-
-
- [1]: ../configurations/common.md#highlight-severity-levels
- [2]: ../how-to.md#how-to-restart-the-language-server
diff --git a/docs/configurations/running-modes.md b/docs/configurations/running-modes.md
new file mode 100644
index 0000000..64881ad
--- /dev/null
+++ b/docs/configurations/running-modes.md
@@ -0,0 +1,70 @@
+Each distribution of Pyright comes with two executables:
+`pyright` (also referred to as "executable") and
+`pyright-langserver` ("language server executable").
+
+Aside from the main functionality discussed here,
+the first also provides a few more features and options,
+some of which are supported or used by this plugin.
+
+Different running modes use different executables.
+
+To make the most of this plugin,
+you are recommended to specify both executables.
+
+
+## Comparison tables
+
+| | `pyright` | `pyright-langserver` |
+|-------------------------------------|--------------------------------------------|-----------------------------------------|
+| Process type | Stops when finishes checking the file(s) | Long-running process |
+| Result | Only type checking diagnostics | Diagnostics and [other LSP features][1] |
+| Performance | Good | Better in many cases |
+| File reading method | From disk | File contents are sent via stdio |
+| [Potentially infinite processes][2] | Long processes are [forcibly destroyed][3] | Processes must be terminated manually |
+
+| | Command line mode | LSP4IJ mode |
+|--------------------|-----------------------------------------------|-------------------------------------------|
+| Executable used | `pyright` | `pyright-langserver` |
+| Executable invoked | After each change | On project/supported file open |
+| Side effect | Will save all files to ensure synchronization | No side effects |
+| Error reporting | Notifications and IDE log | LSP4IJ console, notifications and IDE log |
+
+
+## Command line mode
+
+If this mode is selected, everytime a Python file is edited,
+this plugin will save it along with other (unsaved) files,
+then invoke the executable in a subprocess.
+The result of this process is rerouted back to the IDE
+in the form of visual annotations.
+
+This mode requires two things to work correctly:
+
+* That the executable you provide accepts said arguments, and
+* that it outputs diagnostics in the formats defined [here][4].
+
+If any of these requirements are not met,
+[a notification][5] will be displayed.
+
+Due to backward compatibility, this is the default mode.
+However, for better performance, LSP4IJ mode is recommended.
+
+
+## LSP4IJ mode
+
+If this mode is selected, the language server will be invoked on project open.
+All LSP messages are then handled by [the various features][6]
+of [the LSP4IJ plugin][7], a third-party LSP client for JetBrains IDEs.
+
+[It is possible][8] to use Pyright with LSP4IJ directly,
+but doing so is not recommended.
+
+
+ [1]: https://microsoft.github.io/pyright/#/features?id=language-server-support
+ [2]: ../problems.md#process-timed-out
+ [3]: other.md#process-timeout
+ [4]: https://microsoft.github.io/pyright/#/command-line?id=json-output
+ [5]: ../problems.md
+ [6]: https://github.com/redhat-developer/lsp4ij/blob/main/docs/LSPSupport.md
+ [7]: https://github.com/redhat-developer/lsp4ij
+ [8]: https://github.com/redhat-developer/lsp4ij/blob/main/docs/UserDefinedLanguageServer.md
diff --git a/docs/faq.md b/docs/faq.md
index 3a62d2b..ac34113 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,45 +1,10 @@
# Frequently asked questions
-## What exactly is this plugin doing?
-
-
-### CLI
-
-In a nutshell:
-
-* You edit your code.
-* This plugin saves your (unsaved) files.
-* It then invokes the executable(s) provided by you
- with some hardcoded arguments.
-* The results of which are used to show annotations.
-
-And that's it.
-
-It expects two things:
-
-* That the executable you provide accepts said arguments, and
-* that it outputs diagnostics in the formats specified [here][1].
-
-As long as you respect these requirements,
-you can use your own script, or whatever.
-If you don't, expect some big bad error messages.
-
-
-### LSP
-
-Most of the logic is already defined by either the [@eclipse-lsp4j/lsp4j][2]
-library or [the experimental language server protocol APIs][3].
-LSP simply glues these and the Pyright language server together.
-
-Again, the executable is not checked.
-You can use your own hand-hacked version if you feel like it.
-
-
## My code should have no/these errors, but it does/doesn't.
-Both CLI and LSP contain no type checking logic.
-For type checking bugs, please report them to [the Pyright issue tracker][4].
+This plugin contains no type checking logic.
+For type checking bugs, please report them to [the Pyright issue tracker][1].
## What's the difference between the `pyright` and `pyright-python` files?
@@ -49,7 +14,7 @@ mainly for the purpose of better integration with VSCode.
This requires a dependency on Node, which Python developers
might not have on their development machines.
-[The PyPI `pyright` package][5] was created to solve this problem.
+[The PyPI `pyright` package][2] was created to solve this problem.
When installed, it places 4 proxy executables in
the same virtual environment/directory you have your `pip` in:
@@ -58,7 +23,7 @@ the same virtual environment/directory you have your `pip` in:
These proxies will automatically install the actual NPM package
if it is not already installed, then re-output the results of
-the original executables. [With the correct configurations][6],
+the original executables. [With the correct configurations][3],
new versions may be automatically installed at runtime.
If the corresponding version of the NPM package has not been installed,
@@ -72,50 +37,27 @@ Said original executables can typically be found at:
* Linux: `~/.cache/pyright-python//node_modules/.bin`
-## Why does CLI have to perform saves so often?
+## Why does the plugin have to perform saves so often in command line mode?
Pyright only reads actual files on disk.
It does not support passing files from stdin.
-[A feature request][7] was made and quickly rejected.
+[A feature request][4] was made and quickly rejected.
-Adding an option that makes CLI run only on "manual" saves
+Adding an option that makes the plugin run only on "manual" saves
(the *Save All* action) is counter-productive, since that doesn't
-guarantee the annotator class is called. This is [a known limitation][8].
+guarantee the annotator class is called. This is [a known limitation][5].
-If you use PyCharm Professional, you [should be using][9] LSP instead.
+Use [the LSP4IJ mode][6] instead.
## Is the command-line watch mode (`--watch`) supported?
-Support for `--watch` is on the roadmap.
-There is no ETA, however.
-
-
-## Why does CLI take so long to run on my project?
-
-There are multiple possible reasons for this.
-
-### Other inspections are taking too long
-
-Since CLI invokes a command-line tool, it must be registered
-as an [`ExternalAnnotator`][10]. Inspectors of this kind will
-only run when all other background tasks have finished.
-
-Check your other plugins to see if this is the case.
-
-### There are a lot of files/things to process
-
-Unlike Mypy, Pyright does not cache previous results.
-As such, everytime it runs on a given file,
-it also has to reprocess all other files that file depends on.
-
-Again, for better performance, LSP [is recommended][9].
+No. Use LSP4IJ mode instead.
-### Your code triggers a Pyright bug
-In some rare cases, Pyright might be stuck in an infinite loop or similar.
+## What does this command line option do?
-If this seems to be the case, treat it as [a fatal error][11].
+Refer to [Pyright's documentation][7] for the meaning of these options.
## Is this plugin affiliated with Microsoft/JetBrains?
@@ -127,22 +69,18 @@ It was, however, created out of adoration of Pyright and JetBrains IDEs.
## I love this project. How can I support it?
-You can consider [sponsoring it][12].
+You can consider [sponsoring it][8].
-If you are feeling generous, see [`CONTRIBUTING.md`][13]
+If you are feeling generous, see [`CONTRIBUTING.md`][9]
for how to contribute non-financially.
- [1]: https://microsoft.github.io/pyright/#/command-line?id=json-output
- [2]: https://github.com/eclipse-lsp4j/lsp4j
- [3]: https://plugins.jetbrains.com/docs/intellij/language-server-protocol.html
- [4]: https://github.com/microsoft/pyright/issues
- [5]: https://pypi.org/project/pyright/
- [6]: https://github.com/RobertCraigie/pyright-python/blob/HEAD/README.md#automatically-keeping-pyright-up-to-date
- [7]: https://github.com/microsoft/pyright/issues/7282
- [8]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues/10
- [9]: index.md#choosing-the-right-plugin
- [10]: https://plugins.jetbrains.com/docs/intellij/syntax-highlighting-and-error-highlighting.html#external-annotator
- [11]: problems.md#fatal-error
- [12]: https://github.com/sponsors/InSyncWithFoo
- [13]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md
+ [1]: https://github.com/microsoft/pyright/issues
+ [2]: https://pypi.org/project/pyright/
+ [3]: https://github.com/RobertCraigie/pyright-python/blob/HEAD/README.md#automatically-keeping-pyright-up-to-date
+ [4]: https://github.com/microsoft/pyright/issues/7282
+ [5]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues/10
+ [6]: configurations/running-modes.md
+ [7]: https://microsoft.github.io/pyright/#/command-line
+ [8]: https://github.com/sponsors/InSyncWithFoo
+ [9]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md
diff --git a/docs/features.md b/docs/features.md
index 950f935..2e44919 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -16,15 +16,9 @@ Available actions:
* Absolute path: Set the absolute path.
* Relative path: Set the relative path (no leading dot).
-* Do not suggest: Turn off [the corresponding option][1].
+* Do not suggest: Turn off [the corresponding setting][1].
-=== "CLI"
-
- ![](./assets/cli-features-demo-auto-suggest-executable.png)
-
-=== "LSP"
-
- ![](./assets/lsp-features-demo-auto-suggest-executable.png)
+![](./assets/features-demo-auto-suggest-executable.png)
## Suppressing diagnostics using quick fixes
@@ -65,4 +59,4 @@ the entire list will be removed:
![](./assets/features-demo-diagnostic-suppressing-quick-fixes-no-code-after.png)
- [1]: configurations/common.md#auto-suggest-executable
+ [1]: configurations/executables.md#auto-suggest-executable
diff --git a/docs/how-to.md b/docs/how-to.md
index f5ac81e..879413e 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -1,8 +1,6 @@
## How to install the Pyright executables
-Choose one that works for you (or one you like the most):
-
-!!! tip "Your favourite tool is not here? [Submit a PR!][1]"
+Choose one that works for you:
```shell
$ pip install pyright
@@ -14,27 +12,25 @@ $ bun install pyright
$ brew install pyright
```
-See also [Pyright's official installation guide][2].
+See also [Pyright's official installation guide][1].
## How to restart the language server
-In the status bar, find the cell that has
-"Pyright" next to a pair of braces.
-Click it, then click the loop icon.
+From the LSP Consoles of the Language Servers toolwindow,
+find the line that says "Pyright".
-![](assets/lsp-restart-server-button.png)
+Right click the line below it, then click "Stop".
+The line should then say "Disabled".
+Right click that line again, then click "Restart".
+=== "Stop"
-## How to enable language server logging
+ ![](./assets/lsp4ij-stop-server-button.png)
-Add the following line to the Debug Log Settings panel
-(Help | Diagnostic Tools):
+=== "Restart"
-```text
-#com.intellij.platform.lsp
-```
+ ![](./assets/lsp4ij-restart-server-button.png)
- [1]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md
- [2]: https://microsoft.github.io/pyright/#/installation?id=command-line
+ [1]: https://microsoft.github.io/pyright/#/installation?id=command-line
diff --git a/docs/index.md b/docs/index.md
index 6cf232f..1d8e111 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,44 +1,36 @@
# Pyright for PyCharm user documentation
This site serves as the user documentation for
-the Pyright for PyCharm project.
-The project includes two plugins:
+[the Pyright PyCharm plugin][1].
-| | The CLI-based plugin | The LSP-based plugin |
-|:-----------------|:-------------------------|:------------------------------------|
-| Repository | [pyright-for-pycharm][1] | [pyright-langserver-for-pycharm][2] |
-| Marketplace name | [Pyright][3] | [Pyright Language Server][4] |
-| Codename | CLI | LSP |
+The plugin runs and reroutes Pyright's diagnostics back to your IDE.
+Both PyCharm Professional and PyCharm Community users can use it.
-In this documentation, the two plugins
-will be referred to using their codenames.
+??? question "Looking for the old LSP plugin?"
+ It now has [its own documentation site][2].
-## Choosing the right plugin
-!!! abstract "TLDR: Professional --> LSP; Community --> CLI."
+## Usage
-These two plugins have the same naming conventions,
-are maintained by the same person, have similar (but not identical)
-configurations, but are meant for different target users.
+Go to Settings | Tools |
+Pyright (Global) / Pyright (Project)
+and set the path to [your Pyright executable(s)][3].
-LSP is dependent on [the experimental language server protocol APIs][5]
-which are only available for PyCharm Professional and other paid IDEs
-since 2023.2. This means that PyCharm Community users cannot use it.
+=== "Global"
-On the other hand, CLI can be used by both.
-However, due to its limited capabilities and performance reason,
-it is recommended that PyCharm Professional users use LSP instead.
+ ![](./assets/configurations-global-panel.png)
-!!! warning
+=== "Project"
- Do not install both plugins.
- While doing so will likely cause no technical issues,
- their functionalities overlap a lot.
+ ![](./assets/configurations-project-panel.png)
+Save, return to your files and start making some modifications.
+You should see Pyright annotations in a few seconds.
+If not, refer to [Problems and solutions][4].
- [1]: https://github.com/InSyncWithFoo/pyright-for-pycharm
- [2]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm
- [3]: https://plugins.jetbrains.com/plugin/24145
- [4]: https://plugins.jetbrains.com/plugin/24146
- [5]: https://plugins.jetbrains.com/docs/intellij/language-server-protocol.html
+
+ [1]: https://plugins.jetbrains.com/plugin/24145
+ [2]: https://insyncwithfoo.github.io/pyright-langserver-for-pycharm
+ [3]: configurations/executables.md
+ [4]: problems.md
diff --git a/docs/logging.md b/docs/logging.md
index b34118e..60e5da8 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -1,4 +1,4 @@
-For debugging purposes, the plugins may log some informational data.
+For debugging purposes, the plugin may log some informational data.
When reporting issues, always include the relevant log entries if applicable.
@@ -18,7 +18,7 @@ Note that it might be up to 10 MB in size.
Alternatively, navigate to the directories documented [here][1].
-## CLI
+## Command line mode
| Event | Content | Searching keywords |
|------------------|--------------------------------------|----------------------------------------|
@@ -119,19 +119,13 @@ Exception properties entry format:
```
-## LSP
+## LSP4IJ mode
-| Event | Content | Keywords to look for |
-|--------------|-----------------------|-------------------------------------------|
-| Server start | Plugin configurations | `PyrightLSDescriptor - AllConfigurations` |
-
-
-If language server logging [is enabled][4],
-every request and response will be logged,
-potentially truncated if it is too long.
+| Event | Content | Keywords to look for |
+|--------------|--------------------------|------------------------------------------------------|
+| Server start | Language server settings | `com.insyncwithfoo.pyright.lsp4ij.Client - Settings` |
[1]: https://www.jetbrains.com/help/pycharm/directories-used-by-the-ide-to-store-settings-caches-plugins-and-logs.html#logs-directory
[2]: https://microsoft.github.io/pyright/#/command-line?id=json-output
[3]: https://microsoft.github.io/pyright/#/command-line?id=pyright-exit-codes
- [4]: how-to.md#how-to-enable-language-server-logging
diff --git a/docs/problems.md b/docs/problems.md
index 7facf92..05c424b 100644
--- a/docs/problems.md
+++ b/docs/problems.md
@@ -6,28 +6,21 @@
Make sure that:
* Your project has the correct interpreter set
- (Project | Python Interpreter, or a cell in the status bar).
+ (Project | Python Interpreter).
* [The executable][1] is given and is correct.
* The plugin itself is enabled (Plugins).
-* The corresponding inspection is enabled
- (Editor | Inspections -->
- Pyright diagnostics / Pyright language server diagnostics).
-* (CLI) The file is an actual Python file on disk, not an injected fragment.
-
-??? question "Why does CLI need the file to be an actual file?"
-
- [TLDR][2]: Pyright only supports reading files from disk, not stdin.
+* [The inspection entry][2] is enabled.
Other things to try:
* Reinstall the plugin or update to the latest version.
* Reopen the files, reopen the project or restart the IDE.
-* (LSP) [Restart the language server][3].
+* [Restart the language server][3] (LSP4IJ mode).
* Restart your machine.
* Reinstall/reset the IDE.
If the problem persists, please report it to
-[the corresponding issue tracker][4] with [relevant log entries][5].
+[the plugin's issue tracker][4] with [relevant log entries][5].
## Fatal error
@@ -43,9 +36,8 @@ then report it to [Pyright's issue tracker][6].
This most likely means that the configuration file is invalid in some way.
-To know which file is being used, see [the configuration docs][1].
-Alternatively, use the "Open file" action to
-directly open the file which is reported to be invalid.
+Use the "Open file" action to directly open the file
+which is reported to be invalid.
## Unrecognized command-line options
@@ -55,13 +47,10 @@ doesn't support the options used by the plugin.
If you are using [the official NPM package][7] or
[the community-maintained PyPI package][8],
-please report the problem to [the corresponding issue tracker][4]
+please report the problem to [the plugin's issue tracker][4]
along with the version of Pyright you are using, which can be
retrieved by running ` --version` in your terminal.
-If the executable is something you come up with,
-check the source code for expected options.
-
## Cannot parse output
@@ -76,27 +65,55 @@ For custom executables, maintain compatibility with said version.
## Process timed out
-This means the process did not finish within [the limit defined][10].
+This means the process did not finish within [the limit specified][10].
-There are [multiple possible reasons][11] for this.
+There are multiple possible reasons for this.
Increase the limit as necessary.
+### Other inspections are taking too long
+
+Since the command line mode invokes a command-line tool,
+it must be registered as an [`ExternalAnnotator`][11].
+Inspectors of this kind will only run
+when all other background tasks have finished.
+
+Check your other plugins to see if this is the case.
+
+
+### There are a lot of files/things to process
+
+Unlike Mypy, Pyright does not cache previous results.
+As such, everytime it runs on a given file,
+it also has to reprocess all other files that file depends on.
+
+For better performance, use LSP4IJ mode instead.
+
+
+### Your code triggers a Pyright bug
+
+In some rare cases, Pyright might be stuck in an infinite loop or similar.
+
+If this seems to be the case, treat it as a fatal error.
+
+
## Other problems
-For CLI, you can start debugging by running the commands manually.
-The commands can be retrieved using [the provided IDE action][12].
+For command line mode, you can start debugging
+by running the commands manually.
+The command for the current file can be retrieved
+using [a provided IDE action][12].
- [1]: configurations/cli.md#configuration-file
- [2]: faq.md#why-does-cli-have-to-perform-saves-so-often
+ [1]: configurations/executables.md
+ [2]: configurations/inspection.md
[3]: how-to.md#how-to-restart-the-language-server
- [4]: index.md
+ [4]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues
[5]: logging.md
[6]: https://github.com/microsoft/pyright/issues
[7]: https://www.npmjs.com/package/pyright
[8]: https://pypi.org/project/pyright/
[9]: https://microsoft.github.io/pyright/#/command-line?id=json-output
- [10]: configurations/cli.md#process-timeout
- [11]: faq.md#why-does-cli-take-so-long-to-run-on-my-project
+ [10]: configurations/other.md#process-timeout
+ [11]: https://plugins.jetbrains.com/docs/intellij/syntax-highlighting-and-error-highlighting.html#external-annotator
[12]: actions.md#copy-pyright-command
diff --git a/docs/requirements.txt b/docs/requirements.txt
index c7f9f55..058dd16 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,2 @@
-mkdocs~=1.5.3
-mkdocs-material~=9.5.17
+mkdocs~=1.6.0
+mkdocs-material~=9.5.29
diff --git a/docs/usage.md b/docs/usage.md
deleted file mode 100644
index c34f933..0000000
--- a/docs/usage.md
+++ /dev/null
@@ -1,36 +0,0 @@
-=== "CLI"
-
- Go to Settings | Tools |
- Pyright (Global) / Pyright (Project)
- and set the path to [your Pyright executable][1].
-
- ![](./assets/cli-global-configuration-panel.png)
- ![](./assets/cli-project-configuration-panel.png)
-
- Save, return to your file and start making some modifications.
- You should see Pyright annotations in a few seconds.
- If not, refer to [Problems and solutions][2].
-
-=== "LSP"
-
- Go to Settings | Tools |
- Pyright LS (Global) / Pyright LS (Project)
- and set the path to [your Pyright language server executable][1].
-
- ![](./assets/lsp-global-configuration-panel.png)
- ![](./assets/lsp-project-configuration-panel.png)
-
- You might need to reopen your files or restart the IDE
- for the files to be recognized by the language server.
- If that doesn't work, refer to [Problems and solutions][2].
-
- ## Enable logging
-
- You are strongly encouraged to [enable logging][3].
- This way, all requests and responses will be recorded in `idea.log`
- for further analysis should a problem arises.
-
-
- [1]: configurations/common.md#executable
- [2]: problems.md
- [3]: how-to.md#how-to-enable-language-server-logging
diff --git a/mkdocs.yaml b/mkdocs.yaml
index e8ba484..9223829 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -13,7 +13,7 @@ exclude_docs: |
theme:
name: material
favicon: assets/icon.svg
- logo: assets/icon-outline-10-white.svg
+ logo: assets/icon-outline.svg
palette:
-
media: "(prefers-color-scheme: light)"
@@ -34,6 +34,7 @@ theme:
features:
- content.action.edit
- content.action.view
+ - navigation.indexes
- search.suggest
markdown_extensions:
@@ -62,14 +63,14 @@ markdown_extensions:
nav:
- Overview: index.md
- - Usage: usage.md
- Configurations:
- - Common: configurations/common.md
- - CLI-specific: configurations/cli.md
- - LSP-specific: configurations/lsp.md
- - Related: configurations/related.md
- - Features: features.md
+ - Overview: configurations/index.md
+ - Running modes: configurations/running-modes.md
+ - Executables: configurations/executables.md
+ - Inspection: configurations/inspection.md
+ - Other: configurations/other.md
- IDE actions: actions.md
+ - Other features: features.md
- Problems: problems.md
- Logging: logging.md
- How-to guides: how-to.md
@@ -79,5 +80,6 @@ validation:
omitted_files: warn
absolute_links: warn
unrecognized_links: warn
+ anchors: warn
strict: true
diff --git a/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt b/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt
index b10fa45..e52d369 100644
--- a/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt
+++ b/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt
@@ -103,7 +103,7 @@ private fun Panel.makeGlobalRunningModeInput(block: ButtonsGroup.() -> Unit) = r
}
-private fun Row.makeNumberOfThreadsInput(block: Cell.() -> Unit): Cell = run {
+private fun Row.makeNumberOfThreadsInput(block: Cell.() -> Unit) = run {
val comment = message("configurations.numberOfThreads.comment")
spinner(0..1_000_000, step = 1).comment(comment).apply(block)
}
@@ -165,7 +165,7 @@ internal fun configurationPanel(state: Configurations) = panel {
}
}
- group(message("configurations.group.others")) {
+ group(message("configurations.group.commandLine")) {
row(message("configurations.processTimeout.label")) {
makeProcessTimeoutInput { bindIntValue(state::processTimeout) }
}
diff --git a/src/main/resources/messages/pyright.properties b/src/main/resources/messages/pyright.properties
index c8fb8a8..62717e6 100644
--- a/src/main/resources/messages/pyright.properties
+++ b/src/main/resources/messages/pyright.properties
@@ -2,7 +2,7 @@ configurations.global.displayName = Pyright (Global)
configurations.project.displayName = Pyright (Project)
configurations.group.tooltips = Tooltips (not applied retroactively)
-configurations.group.others = Other settings
+configurations.group.commandLine = Command line mode
configurations.alwaysUseGlobal.label = Always use global executable
configurations.globalExecutable.label = Executable: