Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation improvements #505

Merged
merged 2 commits into from
Jul 19, 2024
Merged

Documentation improvements #505

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bc52b8
document how we keep up-to-date with upstream
DetachHead Jul 19, 2024
b24546c
update development documentation with basedpyright-specific info
DetachHead Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 1 addition & 13 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Contributing


## 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.
Expand All @@ -9,15 +8,4 @@ please upvote issues you find important using the 👍 react. we don't close iss

## local development

although pyright is written in typescript, we've made improvements to the developer experience for python developers who are not familiar with typescript/nodejs. you should be able to work on basedpyright without ever having to install nodejs yourself. the node installation is instead managed by a [pypi package](https://pypi.org/project/nodejs-wheel/) and installed to the project's virtualenv. the only thing you need to have installed already is python (any version from 3.8 to 3.12 should work)

we recommend using vscode, as there are project configuration files in the repo that set everything up correctly (linters/formatters/debug configs, etc).

1. hit `F1` > `Tasks: Run task` > `install dependencies`, or run the following command:
```
./pw pdm install
```
this will install all dependencies required for the project (pyprojectx, pdm, node, typescript, etc.). all dependencies are installed locally to `./.venv` and `./node_modules`
2. press "Yes" when prompted by vscode to use the newly created virtualenv

you can now run any node/npm commands from inside the venv.
[see here](https://docs.basedpyright.com/#/build-debug?id=building-basedpyright)
1 change: 1 addition & 0 deletions docs/_sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@

- Development

- [How we keep up-to-date with upstream](upstream.md)
- [Building & Debugging](build-debug.md)
- [Pyright Internals](internals.md)

Expand Down
36 changes: 10 additions & 26 deletions docs/build-debug.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,17 @@
## Building Pyright
## Building basedpyright

To install the dependencies for all packages in the repo:
1. Install [nodejs](https://nodejs.org/en/) version 16.x
2. Open terminal window in main directory of cloned source
3. Execute `npm run install:all` to install dependencies for projects and sub-projects
although pyright is written in typescript, in basedpyright we've made improvements to the developer experience for python developers who are not familiar with typescript/nodejs. you should be able to work on basedpyright without ever having to install nodejs yourself. the node installation is instead managed by a [pypi package](https://pypi.org/project/nodejs-wheel/) and installed to the project's virtualenv. the only thing you need to have installed already is python (any version from 3.8 to 3.12 should work)

we recommend using vscode, as there are project configuration files in the repo that set everything up correctly (linters/formatters/debug configs, etc).

## Building the CLI
1. hit `F1` > `Tasks: Run task` > `install dependencies`, or run the following command:
```
./pw pdm install
```
this will install all dependencies required for the project (pyprojectx, pdm, node, typescript, etc.). all dependencies are installed locally to `./.venv` and `./node_modules`
2. press "Yes" when prompted by vscode to use the newly created virtualenv

1. cd to the `packages/pyright` directory
2. Execute `npm run build`

Once built, you can run the command-line tool by executing the following:

`node index.js`

## Building the VS Code extension

1. cd to the `packages/vscode-pyright` directory
2. Execute `npm run package`

The resulting package (pyright-X.Y.Z.vsix) can be found in the client directory.
To install in VS Code, go to the extensions panel and choose “Install from VSIX...” from the menu, then select the package.


## Running Pyright tests

1. cd to the `packages/pyright-internal` directory
2. Execute `npm run test`
you can now run any node/npm commands from inside the venv.


## Debugging Pyright
Expand Down
20 changes: 11 additions & 9 deletions docs/internals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@

## Code Structure

* packages/vscode-pyright/src/extension.ts: Language Server Protocol (LSP) client entry point for VS Code extension.
* packages/pyright-internal/typeshed-fallback/: Recent copy of Typeshed type stub files for Python stdlib
* packages/pyright-internal/src/pyright.ts: Main entry point for command-line tool
* packages/pyright-internal/src/server.ts: Main entry point for LSP server
* packages/pyright-internal/src/analyzer: Modules that perform analysis passes over Python parse tree
* 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/vscode-pyright/src/extension.ts`: Language Server Protocol (LSP) client entry point for VS Code extension.
* `packages/pyright-internal/typeshed-fallback/`: Recent copy of Typeshed type stub files for Python stdlib
* `packages/pyright-internal/src/pyright.ts`: Main entry point for command-line tool
* `packages/pyright-internal/src/server.ts`: Main entry point for LSP server
* `packages/pyright-internal/src/analyzer`: Modules that perform analysis passes over Python parse tree
* `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))
* `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](https://docs.basedpyright.com/#/?id=docstrings-for-compiled-builtin-modules) (generated from `packages/pyright-internal/typeshed-fallback/` when building the pypi package)

## Core Concepts

Expand Down
12 changes: 12 additions & 0 deletions docs/upstream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# how we keep up-to-date with upstream

every time pyright releases a new version, we merge its release tag into basedpyright. each basedpyright version is based on a release version of pyright.

you can check which pyright version basedpyright is based on by running `basedpyright --version`:

```
basedpyright 1.14.0
based on pyright 1.1.372
```

we try to update basedpyright as soon as a new pyright version is released. we typically release on the same day that pyright does.
Loading