more improvements and fixes to the docs

.github/ISSUE_TEMPLATE.md

@@ -6,5 +6,5 @@ thanks for taking the time to raise an issue. please consider the following:
   - note that the default rules are different in pyright (most checks are disabled by default). make sure to check the configuration options on the sidebar if your issue is with a specific diagnostic rule
   - if it does also occur in pyright, has it been raised upstream at https://github.com/microsoft/pyright? this isn't required, but it's useful to know if the problem has already been discussed. also if you're lucky and your issue doesn't get rejected, chances are it will be fixed faster.
 - if you're reporting an issue installing basedpyright, please mention what operating system and python version you're using
-- if you're interested in fixing the issue yourself, we've tried our best to make the process to get set up for local development as easy as possible: https://docs.basedpyright.com/latest/development/build-debug/
+- if you're interested in fixing the issue yourself, we've tried our best to make the process to get set up for local development as easy as possible: https://docs.basedpyright.com/latest/development/contributing/#building
 -->

README.md

@@ -9,7 +9,7 @@
 [![pycharm](https://img.shields.io/jetbrains/plugin/v/24145?logo=pycharm)](https://plugins.jetbrains.com/plugin/24145)
 [![homebrew](https://img.shields.io/homebrew/installs/dm/basedpyright?logo=homebrew&color=fbb040)](https://formulae.brew.sh/formula/basedpyright)
 [![Discord](https://img.shields.io/discord/948915247073349673?logo=discord&color=5865F2)](https://discord.gg/7y9upqPrk2)
-[![basedpyright - checked](https://img.shields.io/badge/basedpyright-checked-42b983)](https://detachhead.github.io/basedpyright)
+[![basedpyright - checked](https://img.shields.io/badge/basedpyright-checked-42b983)](https://docs.basedpyright.com)
 
 Basedpyright is a fork of [pyright](https://github.com/microsoft/pyright) with various type checking improvements, improved vscode support and pylance features built into the language server.
 

docs/benefits-over-pyright/pylance-features.md

@@ -2,7 +2,7 @@
 
 basedpyright re-implements some of the features that microsoft made exclusive to pylance, which is microsoft's closed-source vscode extension built on top of the pyright language server with some additional exclusive functionality ([see the pylance FAQ for more information](https://github.com/microsoft/pylance-release/blob/main/FAQ.md#what-features-are-in-pylance-but-not-in-pyright-what-is-the-difference-exactly)).
 
-the following features have been re-implemented in basedpyright's language server, meaning they are no longer exclusive to vscode. you can use any editor that supports the [language server protocol](https://microsoft.github.io/language-server-protocol/). for more information on installing pyright in your editor of choice, see [the installation instructions](https://detachhead.github.io/basedpyright/#/installation).
+the following features have been re-implemented in basedpyright's language server, meaning they are no longer exclusive to vscode. you can use any editor that supports the [language server protocol](https://microsoft.github.io/language-server-protocol/). for more information on installing pyright in your editor of choice, see [the installation instructions](../installation/ides.md).
 
 ## import suggestion code actions
 

docs/configuration.md

@@ -71,7 +71,7 @@ The following settings control pyright’s diagnostic output (warnings or errors
 
 - **typeCheckingMode** ["off", "basic", "standard", "strict", "all"]: Specifies the default rule set to use. Some rules can be overridden using additional configuration flags documented below. The default value for this setting is "all". If set to "off", all type-checking rules are disabled, but Python syntax and semantic errors are still reported.
 
-- **ignore** [array of paths, optional]: Paths of directories or files whose diagnostic output (errors and warnings) should be suppressed even if they are an included file or within the transitive closure of an included file. Paths may contain wildcard characters ** (a directory or multiple levels of directories), * (a sequence of zero or more characters), or ? (a single character). This setting can be overridden in VS code in your settings.json.
+- **ignore** [array of paths, optional]: Paths of directories or files whose diagnostic output (errors and warnings) should be suppressed even if they are an included file or within the transitive closure of an included file. Paths may contain wildcard characters ** (a directory or multiple levels of directories), * (a sequence of zero or more characters), or ? (a single character). This setting can be overridden using the [language server settings](./language-server-settings.md).
 
 ### Type Check Rule Overrides
 

docs/configuration/command-line.md

@@ -2,7 +2,7 @@
 
 Usage: basedpyright [options] [files...] (1)
 
-basedpyright can be run as either a VS Code extension or as a command-line tool. The command-line version allows for the following options:
+basedpyright can be run as either a language server or as a command-line tool. The command-line version allows for the following options:
 
 | Flag                               | Description                                           |
 | :--------------------------------- | :---------------------------------------------------  |

docs/configuration/language-server-settings.md

@@ -1,5 +1,7 @@
 # Language Server Settings
 
+## settings
+
 !!! info "for users migrating from pyright or pylance"
     with the exception of `python.pythonPath` and `python.venvPath`, settings prefixed with `python.*` are not supported in basedpyright. use `basedpyright.*` instead.
 
@@ -23,14 +25,14 @@ The basedpyright language server honors the following settings.
 
 **basedpyright.analysis.logLevel** ["Error", "Warning", "Information", or "Trace"]: Level of logging for Output panel. The default value for this option is "Information".
 
-**python.pythonPath** [path]: Path to Python interpreter. This setting is being deprecated by the VS Code Python extension in favor of a setting that is stored in the Python extension’s internal configuration store. Pyright supports both mechanisms but prefers the new one if both settings are present.
+**python.pythonPath** [path]: Path to Python interpreter. if you're using vscode, this setting is being deprecated by the VS Code Python extension in favor of a setting that is stored in the Python extension’s internal configuration store. Pyright supports both mechanisms but prefers the new one if both settings are present.
 
 **python.venvPath** [path]: Path to folder with subdirectories that contain virtual environments. The `python.pythonPath` setting is recommended over this mechanism for most users. For more details, refer to the [import resolution](../usage/import-resolution.md#configuring-your-python-environment) documentation.
 
 !!! note "a note about `python.venvPath`"
     if your venv path is the same for all users working on your project (which should be the case if you're using [uv](https://docs.astral.sh/uv/pip/compatibility/#virtual-environments-by-default) or [pdm](https://pdm-project.org/en/latest/usage/venv/#virtualenv-auto-creation)), we recommend configuring `venvPath` in [a config file](./config-files.md) instead. see [discouraged settings](#discouraged-settings) below for more information.
 
-## based settings
+### based settings
 
 the following settings are exclusive to basedpyright
 
@@ -46,7 +48,7 @@ the following settings are exclusive to basedpyright
 
 ![](inlayHints.functionReturnTypes.png)
 
-## discouraged settings
+### discouraged settings
 
 these options can also be configured [using a config file](./config-files.md). it's recommended to use either a `pyproject.toml` or `pyrightconfig.json` file instead of the language server to configure type checking for the following reasons:
 
@@ -71,4 +73,43 @@ however these settings are still suppored to maintain compatibility with pyright
 
 **basedpyright.analysis.typeshedPaths** [array of paths]: Paths to look for typeshed modules. Pyright currently honors only the first path in the array.
 
-**basedpyright.analysis.useLibraryCodeForTypes** [boolean]: Determines whether pyright reads, parses and analyzes library code to extract type information in the absence of type stub files. Type information will typically be incomplete. We recommend using type stubs where possible. The default value for this option is true.
+**basedpyright.analysis.useLibraryCodeForTypes** [boolean]: Determines whether pyright reads, parses and analyzes library code to extract type information in the absence of type stub files. Type information will typically be incomplete. We recommend using type stubs where possible. The default value for this option is true.
+
+## where do i configure these settings?
+
+the way you configure the basedpyright language server depends on your IDE. below are some examples for [some of the supported editors](../installation/ides.md). this is not a comprehensive list, so if your editor is missing, consult the documentation for its language server support.
+
+### vscode / vscodium
+
+the basedpyright language server settings can be configured using a workspace or global `settings.json`:
+
+```json title="./.vscode/settings.json"
+{
+    "basedpyright.analysis.diagnosticMode": "openFilesOnly"
+}
+```
+
+### neovim
+
+the language server can be configured in your neovim settings:
+
+```lua
+require("lspconfig").basedpyright.setup {
+  basedpyright = {
+    analysis = {
+      diagnosticMode = "openFilesOnly",
+    }
+  }
+}
+```
+
+### helix
+
+```toml title="languages.toml"
+[language-server.basedpyright]
+command = "basedpyright-langserver"
+args = ["--stdio"]
+
+[language-server.basedpyright.config]
+basedpyright.analysis.diagnosticMode = "openFilesOnly"
+```

docs/development/build-debug.md → docs/development/contributing.md

@@ -1,4 +1,10 @@
-# building & debugging
+# Contributing
+
+## Github Issues
+
+unlike the upstream pyright repo, we are very open to ideas for improvements and bug reports. if you've raised an issue on the upstream pyright repo that was closed without a solution, feel free to [raise it again here](https://github.com/DetachHead/basedpyright/issues/new).
+
+please upvote issues you find important using the 👍 react. we don't close issues that don't get enough upvotes or anything like that. this is just to help us prioritize which issues to address first.
 
 ## Building
 

docs/development/internals.md

@@ -1,4 +1,4 @@
-# Pyright Internals
+# basedpyright Internals
 
 ## Code Structure
 
@@ -10,7 +10,8 @@
 * `packages/pyright-internal/src/common`: Modules  that are common to the parser and analyzer
 * `packages/pyright-internal/src/parser`: Modules that perform tokenization and parsing of Python source
 * `packages/pyright-internal/src/tests`: Tests for the parser and analyzer
-* `packages/pyright`: basedpyright npm package (used internally by [the playground](http://basedpyright.com))
+* `packages/pyright`: basedpyright npm package (used internally by the pypi package)
+* `packages/browser-pyright`: basedpyright build that can run in a browser (used internally by [the playground](https://basedpyright.com))
 * `basedpyright`: pypi package wrapper for the npm package, so that users don't need to install nodejs themselves
 * `docstubs`: stubs with [docstrings on compiled modules](../benefits-over-pyright/pylance-features.md#docstrings-for-compiled-builtin-modules) (generated from `packages/pyright-internal/typeshed-fallback/` when building the pypi package)
 

docs/installation/ides.md

@@ -65,7 +65,7 @@ have the version of BasedPyright maintained and upgraded by Mason project.
 ### Setting-up Neovim
 
 BasedPyright is available through the
-[`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#basedpyright)
+[`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#basedpyright)
 adapter for native Neovim's LSP support.
 
 After having both, the client-side plugin and the LSP server command installed,

docs/usage/commands.md

@@ -1,6 +1,6 @@
-# VS Code Commands
+# Language Server Commands
 
-basedyright offers the following commands, which can be invoked from VS Code’s “Command Palette”, which can be accessed from the View menu or by pressing Cmd-Shift-P.
+basedyright offers the following language server commands, which can be invoked from, for example, VS Code’s “Command Palette”, which can be accessed from the View menu or by pressing Cmd-Shift-P.
 
 ## Organize Imports
 This command reorders all imports found in the global (module-level) scope of the source file. As recommended in PEP8, imports are grouped into three groups, each separated by an empty line. The first group includes all built-in modules, the second group includes all third-party modules, and the third group includes all local modules.

docs/usage/import-resolution.md

@@ -36,7 +36,7 @@ Pyright uses the following mechanisms (in priority order) to determine which Pyt
 
 1. If a `venv` name is specified along with a `python.venvPath` setting (or a `--venvpath` command-line argument), it appends the venv name to the specified venv path. This mechanism is not recommended for most users because it is less robust than the next two options because it relies on pyright’s internal logic to determine the import resolution paths based on the virtual environment directories and files. The other two mechanisms (2 and 3 below) use the configured python interpreter to determine the import resolution paths (the value of `sys.path`).
 
-2. Use the `python.pythonPath` setting. This setting is defined by the VS Code Python extension and can be configured using the Python extension’s environment picker interface. More recent versions of the Python extension no longer store the selected Python environment in the `python.pythonPath` setting and instead use a storage mechanism that is private to the extension. Pyright is able to access this through an API exposed by the Python extension.
+2. Use the `python.pythonPath` setting. This setting is defined in the language server. if using VS Code, this can be configured using the Python extension’s environment picker interface. More recent versions of the Python extension no longer store the selected Python environment in the `python.pythonPath` setting and instead use a storage mechanism that is private to the extension. Pyright is able to access this through an API exposed by the Python extension.
 
 3. As a fallback, use the default Python environment (i.e. the one that is invoked when typing `python` in the shell).
 

docs/usage/type-stubs.md

@@ -21,7 +21,7 @@ If you use only a few classes, methods or functions within a library, writing a
 
 To generate a type stub file from within VS Code, enable the reportMissingTypeStubs” setting in your pyrightconfig.json file or by adding a comment `# pyright: reportMissingTypeStubs=true` to individual source files. Make sure you have the target library installed in the python environment that pyright is configured to use for import resolution. Optionally specify a “stubPath” in your pyrightconfig.json file. This is where pyright will generate your type stub files. By default, the stubPath is set to "./typings".
 
-#### Generating Type Stubs in VS Code
+#### Generating Type Stubs in your IDE
 If “reportMissingTypeStubs” is enabled, pyright will highlight any imports that have no type stub. Hover over the error message, and you will see a “Quick Fix” link. Clicking on this link will reveal a popup menu item titled “Create Type Stub For XXX”. The example below shows a missing typestub for the `django` library.
 
 ![Pyright](CreateTypeStub1.png)
@@ -30,8 +30,13 @@ Click on the menu item to create the type stub. Depending on the size of the lib
 
 ![Pyright](CreateTypeStub2.png)
 
+!!! note
+
+    these instructions are specific to VScode, but this functionality is also available in [other supported editors](../installation/ides.md) as well, since this functionality is built into [the language server](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_codeAction).
+
+
 #### Generating Type Stubs from Command Line
-The command-line version of pyright can also be used to generate type stubs. As with the VS Code version, it must be run within the context of your configured project. Then type `pyright --createstub [import-name]`.
+The command-line version of pyright can also be used to generate type stubs. As with the IDE version, it must be run within the context of your configured project. Then type `pyright --createstub [import-name]`.
 
 For example:
 `pyright --createstub django`

packages/pyright/README.md

@@ -2,10 +2,10 @@
 
 basedpyright is a pyright fork with various type checking improvements, improved vscode support and pylance features built into the language server.
 
-**[full documentation](https://detachhead.github.io/basedpyright/)**
+**[full documentation](https://docs.basedpyright.com)**
 
 ## ⚠ warning
 
-this npm package is only really intended for internal use. the recommended way to install basedpyright is [from pypi](https://pypi.org/project/basedpyright/). see [the docs for more information](https://detachhead.github.io/basedpyright/#/?id=published-as-a-pypi-package-no-nodejs-required).
+this npm package is only really intended for internal use. the recommended way to install basedpyright is [from pypi](https://pypi.org/project/basedpyright/). see [the docs for more information](https://docs.basedpyright.com/latest/benefits-over-pyright/pypi-package-vscode-pinning/).
 
 if you have a use case for the npm package, feel free to [raise an issue](https://github.com/DetachHead/basedpyright/issues).