Skip to content

Commit

Permalink
'24 summer documentation revamp.
Browse files Browse the repository at this point in the history 
Signed-off-by: Jos Verlinde <Jos.Verlinde@microsoft.com>
  • Loading branch information
@Josverl
Josverl committed Aug 16, 2024
1 parent 2b6926d commit be14c55
Show file tree
Hide file tree
Showing 45 changed files with 2,785 additions and 2,285 deletions.
47 changes: 46 additions & 1 deletion .vscode/settings.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,52 @@
},
"peacock.color": "#215732",
"cSpell.words": [
"Loboris"
"builtins",
"clearcache",
"colorstubs",
"contextlib",
"cpython",
"debugpy",
"docstrings",
"docstubs",
"firmwares",
"flatgithub",
"flatview",
"genindex",
"josverl",
"Loboris",
"LVGL",
"maxdepth",
"microbit",
"modindex",
"mpremote",
"mypy",
"MYPYPATH",
"Pico",
"PSRAM",
"pwsh",
"pycopy",
"pylance",
"pylint",
"pylintrc",
"pyproject",
"pyright",
"pyrightconfig",
"SAMD",
"spiram",
"stdlib",
"stinos",
"stubgen",
"toctree",
"Traceback",
"typeshed",
"ulab",
"unicore",
"urequests",
"venv",
"virtualenv",
"Webassembly",
"WROVER"
],
"peacock.affectEditorGroupBorder": true,
"peacock.affectPanelBorder": true,
Expand Down
161 changes: 120 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# micropython-stubs
# MicroPython Stubs: Enhance Your Development Experience

[![Documentation Status](https://readthedocs.org/projects/micropython-stubs/badge/?version=latest)](https://micropython-stubs.readthedocs.io/en/latest/?badge=latest "Document build status badge")
[![Star on GitHub](https://img.shields.io/github/stars/josverl/micropython-stubs.svg?style=social)](https://github.com/josverl/micropython-stubs/stargazers)
Expand All @@ -10,76 +10,155 @@
<img src="docs/img/colorstubs.jpg"
alt="pencil stubs"
width=0%
height=20%
height=20%Welcome to the MicroPython Stubs repository! Here, you’ll find a treasure trove of over 3,000 stub files generated by the MicroPython-Stubber tool. Whether you’re just starting out or a seasoned developer, these stubs are designed to supercharge your MicroPython development process.

What Are Stubs?
Stubs are like cheat sheets for your code. They provide hints, auto-completion, and static type checking, making your life as a developer easier and more productive. Here’s what you can expect from these MicroPython stubs:

Faster Coding: With stubs, you’ll write code more quickly and confidently. No more guessing function names or parameters!

Fewer Errors: Stubs help catch mistakes early. If you provide incorrect arguments, you’ll get immediate feedback.

Code Completion: Say goodbye to endless Googling. Stubs provide context-aware auto-completion, even for board-specific features.

Static Type Checking: By adding typing information, you’ll catch type-related bugs before they cause runtime issues.

DEMO NEEDS UPDATE

Demo using VSCode:


Installation
Option 1: Typings Folder (Recommended)
Install the stubs in a typings folder within your project:

pip install -U micropython-<port>[-<board>]stubs --no-user --target ./typings
Enjoy enhanced code completion and type checking!

Option 2: Virtual Environment (venv)
Activate your virtual environment (if you’re using one).

Install the stubs:

pip install -U micropython-<port>[-<board>]stubs --no-user
Dive into the world of MicroPython development with confidence!

[TIPS]

Requirements File: Consider adding a requirements-dev.txt file to your project with the specified stubs. It’ll help keep your development environment consistent.

More examples:

pip install -U micropython-stm32-stubs --target typings --no-user

# Install stubs for a specific version.

pip install -U micropython-esp32-stubs==1.20.0.* --target typings --no-user

# Install stubs for a specific board.

pip install -U micropython-rp2-pico_w-stubs --target typings --no-user
S
style="float: right; margin-right: 10px;" />

Welcome to the MicroPython Stubs repository! Here, you’ll find a treasure trove of over 3,000 stub files generated by the MicroPython-Stubber tool. Whether you’re just starting out or a seasoned developer, these stubs are designed to supercharge your MicroPython development process.

## What Are Stubs?

This repo stores stubs generated by the [MicroPython-Stubber](https://github.com/Josverl/micropython-stubber#readme) tool.
Currently over 3.000 stubfiles of multiple MicroPython versionas and modules are available to help you :
- write code quicker
- with less errors,
- get help from code completion,
- use static type checking,
- and improve the overall development experience while writing [MicroPython](https://micropython.org/).
Stubs are like cheat sheets for your code. They provide hints, auto-completion, and static type checking, making your life as a developer easier and more productive. Here’s what you can expect from these MicroPython stubs:

The stubs are packaged and published to PyPi as [Pep 561 stub-only](https://peps.python.org/pep-0561/#stub-only-packages) packages to allow them to be installed and used with ease.
1. **Faster Coding**: With stubs, you’ll write code more quickly and confidently. No more guessing function names or parameters!
2. **Fewer Errors**: Stubs help catch mistakes early. If you provide incorrect arguments, you’ll get immediate feedback.
3. **Code Completion**: Say goodbye to endless Googling. Stubs provide context-aware auto-completion, even for board-specific features.
4. **Static Type Checking**: By adding typing information, you’ll catch type-related bugs before they cause runtime issues.

<mark>DEMO NEEDS UPDATE</mark>

**Demo using VSCode:**
![demo](docs/img/demo.gif)

## To install
- Install in a typings folder (recommended)
`pip install -U micropython-<port>[-<board>]stubs --no-user --target ./typings`
- Install in a venv (after activating)
`pip install -U micropython-<port>[-<board>]stubs --no-user`
#### Installation

### Option 1: Typings Folder (Recommended)

1. Install the stubs in a `typings` folder within your project:

```bash
pip install -U micropython-<port>[-<board>]stubs --no-user --target ./typings
```

2. Enjoy enhanced code completion and type checking!

### Option 2: Virtual Environment (venv)

Examples:
``` bash
pip install -U micropython-stm32-stubs
1. Activate your virtual environment (if you’re using one).

2. Install the stubs:

```bash
pip install -U micropython-<port>[-<board>]stubs --no-user
```

3. Dive into the world of MicroPython development with confidence!

##

> [TIPS]
>
> **Requirements File**: Consider adding a `requirements-dev.txt` file to your project with the specified stubs. It’ll help keep your development environment consistent.
More examples:

```bash
pip install -U micropython-stm32-stubs --target typings --no-user

# Install stubs for a specific version.
pip install -U micropython-esp32-stubs==1.20.0.*
pip install -U micropython-esp32-stubs==1.20.0.* --target typings --no-user

# Install stubs for a specific board.
pip install -U micropython-rp2-pico_w-stubs

# install to a typings folder (for use without a .venv by pyright or pylance)
pip install -U micropython-rp2-stubs --target typings --no-user
pip install -U micropython-rp2-pico_w-stubs --target typings --no-user
```

## Static Type Checking

Take it up a notch! Combine the stubs with Python static type checkers like Pylance, Pyright, or Mypy. You’ll catch errors even before running your code.

For more details how to use the stubs please refer to [the documentation on RTD](https://micropython-stubs.readthedocs.io/en/latest/20_using.html)

## Current MicroPython stub packages
##](docs/firmware_grp.md)

You can search for [Micropython stub packages on PyPI][PYPI]
<mark>TODO: Add Link</mark>

For a full overview of all stubs check out [the documentation on read the docs](https://micropython-stubs.readthedocs.io/en/latest/firmware_grp.html), or in [docs/firmware_grp.md](docs/firmware_grp.md)
## Explore Available Stubs

## Usage statistics
Curious about which versions, ports, and boards are covered? Check out the [online viewer](https://flatgithub.com/Josverl/micropython-stubs/?filename=all_modules.json) or search for [MicroPython stub packages on PyPI](PYPI).

The following graph shows the number of downloads of the stubs from PyPi over time.
Im not sure what causes the spikes in downloads, but it is interesting to see that the number of downloads is increasing over time, and some of the spikes have corrolation to the publication of new MicroPython versions.
For a comprehensive overview of all stubs, dive into the documentation on [the documentation on read the docs](https://micropython-stubs.readthedocs.io/en/latest/firmware_grp.html).

<table>
<tr>
<td><img src="statistics/month_port.png"></td>
<td><img src="statistics/month_version.png"> </td>
</tr>
<tr>
<td><img src="statistics/pie_port.png"> </td>
<td><img src="statistics/board_version.png"> </td>
</tr>
</table>
## Sponsoring

In order to build accurate stubs I need access to a board to flash it with a specific version of micropython an run part of the stubbing software on the board.

You can help me by:

In addition some tools such as [the MicroPico VSCode extension](https://marketplace.visualstudio.com/items?itemName=paulober.pico-w-go) bundle a version of the stubs with their distribution, so the actual usage is higher than the number of downloads.
- running the software and sharing a PR with the generated MCU stubs,

- sending me a spare board you may have,

- or by sponsoring me though Github

## Contributors

Thanks to everyone that has submitted stubs or other relevant pieces of code and information, or published relevant stubs on pypi or github.

Add authors of typings.py

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

<!-- prettier-ignore-start -->

<!-- markdownlint-disable -->

<table>
<tbody>
<tr>
Expand Down Expand Up @@ -117,6 +196,7 @@ Thanks to everyone that has submitted stubs or other relevant pieces of code and
</table>

<!-- markdownlint-restore -->

<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->
Expand All @@ -125,7 +205,6 @@ I invite everyone that has generated stubs for a board or port not on the curren

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.


[samples]: https://github.com/josverl/micropython-stubs/tree/main/docs/samples
[Discussions]: https://github.com/Josverl/micropython-stubs/discussions/categories/ideas
[PYPI]: https://pypi.org/search/?q=-stubs&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+MicroPython
73 changes: 0 additions & 73 deletions docs/10_intro_stubs.md
View file

This file was deleted.

54 changes: 54 additions & 0 deletions docs/10_introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
(intro)=
# Introduction to MicroPython Stubs

![logo of pencil stubs](img/colorstubs.jpg){w=300px align=right}
Welcome to the MicroPython Stubs repository! Here, you’ll find a treasure trove of over 3,000 stub files generated by the MicroPython-Stubber tool. Whether you’re just starting out or a seasoned developer, these stubs are designed to supercharge your MicroPython development process.

This repo stores stubs generated by the [MicroPython-Stubber](https://github.com/Josverl/micropython-stubber#readme) tool
which combines documentation with introspection to build a comprehensive set of stubs for MicroPython.

Currently over 3.000 stub files of multiple MicroPython versions and modules are available to help you :

- write code quicker
- with less errors,
- get help from code completion,
- use static type checking,
- and improve the overall development experience while writing [MicroPython](https://micropython.org/).

```{figure} img/demo.gif
Using the MicroPython Stubs in VSCode with Pylance.
```

## What are type stubs?

Stubs are like cheat sheets for your code. They provide hints, auto-completion, and static type checking, making your life as a developer easier and more productive. Here’s what you can expect from these MicroPython Stubs:

1. **Faster Coding**: With stubs, you’ll write code more quickly and confidently. No more guessing function names or parameters!
2. **Fewer Errors**: Stubs help catch mistakes early. If you provide incorrect arguments, you’ll get immediate feedback.
3. **Code Completion**: Say goodbye to endless Googling. Stubs provide context-aware auto-completion, even for board-specific features.
4. **Static Type Checking**: By adding typing information, you’ll catch type-related bugs before they cause runtime issues.

The stubs are packaged and published to PyPi as [Pep 561 stub-only](https://peps.python.org/pep-0561/#stub-only-packages) packages to allow them to be installed and used with ease.

Type stubs are used by IDEs, linters, and static type checkers to provide a better development experience. They’re especially useful for MicroPython, where the dynamic nature of the language , and the differences between the different ports and boards can make it hard to catch errors early.

## Benefits of using MicroPython Stubs

If you:

- Use a modern Editor or IDE that supports Python static type checking
- Install the MicroPython Stubs on you computer (not on the MCU)
- Add some basic configuration to your IDE
- Use static type checking in your development process

Y=ou can benefit from:

- MicroPython specific auto completion, of arguments and things like board specific Pin names
- Tooltips with documentation of the MicroPython stdlib and included modules , specific to you port and board
- Direct feedback or errors if you provide incorrect parameters to functions or methods
- Adding additional checks to you CI/CD Pipelines to catch errors before they are merged into the main branch
- Refactor with confidence, knowing that the type checker will help you catch more errors.


<!-- TODO: Add code sampled / gif of unannotated code -->

Loading

0 comments on commit be14c55

Please sign in to comment.