mirror of
https://github.com/pybricks/pybricks-api.git
synced 2026-09-12 09:37:25 +00:00
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
**Project:** `pybricks-api`
|
|
|
|
**Acceptable changes:**
|
|
|
|
- Fixing typos, spelling, grammar, etc.
|
|
- Clarifying existing documentation.
|
|
- Improving code completion/intellisense.
|
|
|
|
Other more substantial changes should be discussed first by [opening an issue
|
|
on GitHub][issues]. Proposals for new APIs should be discussed in the
|
|
[pybricks-micropython][pbmp] repository since that is where the new features
|
|
will actually be implemented.
|
|
|
|
|
|
[issues]: https://github.com/pybricks/pybricks-api/issues
|
|
[pbmp]: https://github.com/pybricks/pybricks-micropython
|
|
|
|
|
|
**Commit messages:**
|
|
|
|
- Commit messages have a one-line subject, a blank line and a multiline body:
|
|
|
|
prefix: subject
|
|
|
|
body...
|
|
|
|
- Use a prefix to categorize the change. Usually this is the path the the file
|
|
being changed.
|
|
- If it is a documentation change, it can be shortened to `doc/<file>` (omit
|
|
`api` from the path).
|
|
- If it is an API change (in the `pybricks` folder), write `api/<file>`
|
|
instead of `pybricks/<file>`.
|
|
- The subject briefly describes _what_ was changed, e.g. `fix typo`.
|
|
- The body describes _why_ the change was made, e.g. `The word "sensor" was
|
|
spelled incorrectly`.
|
|
- See the [commit history][commits] for more examples.
|
|
|
|
[commits]: https://github.com/pybricks/pybricks-api/commits/master
|
|
|
|
|
|
**Development environment:**
|
|
|
|
Prerequisites:
|
|
- [VS Code][vscode] (optional but recommended)
|
|
- [Git][git]
|
|
- [Python 3][python]
|
|
- [Poetry][poetry]
|
|
|
|
Information on installing prerequisites can be found on the [pybricks-micropython
|
|
wiki][wiki].
|
|
|
|
Initial setup:
|
|
|
|
git clone --recursive https://github.com/pybricks/pybricks-api
|
|
cd pybricks-api
|
|
poetry install
|
|
|
|
Build docs:
|
|
|
|
# Linux
|
|
poetry run make -C doc html
|
|
xdg-open doc/api/build/html/index.html
|
|
|
|
# macOS
|
|
poetry run make -C doc html
|
|
open doc/api/build/html/index.html
|
|
|
|
# Windows (PowerShell)
|
|
poetry run doc\make.bat html
|
|
Invoke-Item doc\api\build\html\index.html
|
|
|
|
Linting:
|
|
|
|
poetry run flake8 # check Python
|
|
poetry run doc8 # check Restructured Text
|
|
|
|
[vscode]: https://code.visualstudio.com/
|
|
[git]: https://git-scm.com/
|
|
[python]: https://www.python.org/
|
|
[poetry]: https://python-poetry.org/
|
|
[wiki]: https://github.com/pybricks-micropython/wiki
|