David Lechner
2c4685f594
This splits the Sphinx tag option from SPHINXOPTS. This allows us to specify the tag without having to remember to add -W and -t. It also fixes not being able to specify the tag with make.bat on Windows. While we are touching this, redundant SOURCEDIR uses are removed (main is already the default) and the .github/workflows/publish-ide-docs.yml script is fixed (ide directory no longer exists).
2.6 KiB
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. Proposals for new APIs should be discussed in the pybricks-micropython repository since that is where the new features will actually be implemented.
Commit messages:
-
Commit messages have a one-line subject, a blank line and a multiline body:
prefix: Subject of the change. body... -
Use a prefix to categorize the change:
- Use the import path as the prefix whenever possible. Examples:
- pybricks.tools: Add StopWatch class.
- pybricks.tools: Reorganize RST files.
- pybricks.tools.StopWatch: Fix return type.
- pybricks.tools.wait: Add example of waiting.
- pybricks.pupdevices: Fix all sensor class ports.
- umath.sin: Fix spelling of Hypotenuse.
- If an import path makes no sense, just use the file path without extensions:
- .vscode/settings: Fix file associations.
- Use the import path as the prefix whenever possible. Examples:
-
The subject briefly describes what was changed. Use a short full sentence as in the examples above.
-
The body describes why the change was made, e.g.
The word "sensor" was spelled incorrectly.
Development environment:
Prerequisites:
Information on installing prerequisites can be found on the pybricks-micropython 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/main/build/html/index.html
# macOS
poetry run make -C doc html
open doc/main/build/html/index.html
# Windows (PowerShell)
poetry run doc\make.bat html
Invoke-Item doc\main\build\html\index.html
Building IDE docs variant:
# Linux/macOS
poetry run make -C doc html TAG=ide
# Windows (PowerShell)
$env:TAG="ide"
poetry run doc\make.bat html
Linting:
poetry run flake8 # check Python
poetry run doc8 # check Restructured Text