CONTRIBUTING.md

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.

• 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.

General docstring principles:

The stubs libraries in this repository have two different purposes:

1. Auto-generating documentation with Sphinx. For this purpose, the documentation should be concise and clear.
2. Provide autocomplete and intellisense in code editors. For this purpose, the code needs to be 100% correct. This way, computers can parse your code correctly and tell you when something is wrong.

Since these objectives don't always align, we address these separately in the stubs library:

1. The first line(s) of the docstring contain the function or method signature as it should be displayed in the human-readable documentation.
2. The real function signature can be as complex as it needs to be to make it correct for intellisense. Overloads can be uses if needed.

In the rare case where the docstring signature is the same as the typed version, we'll still include it for consistency.

Docstring details:

Make sure to look at existing function signatures and docstrings for inspiration when documenting new functionality. As an example, consider:

def run_until_stalled(
    self,
    speed: Number,
    then: Stop = Stop.COAST,
    duty_limit: Optional[Number] = None,
) -> int:
    """
    run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int: deg

    Runs the motor at a constant speed until it stalls.

    Arguments:
        speed (Number, deg/s): Speed of the motor.
        then (Stop): What to do after coming to a standstill.
        duty_limit (Number, %): Duty cycle limit during this
            command. This is useful to avoid applying the full motor
            torque to a geared or lever mechanism. If it is ``None``, the
            duty limit won't be changed during this command.

    Returns:
        Angle at which the motor becomes stalled.
    """

The real method signature at the top contains the full detail, including the type of each argument and return value.

The docstring starts with the signature. Use more than one signature if needed to represent overloaded methods. The signatures are written in the way they should be displayed in the docs:

• Argument types are omitted because they are also shown with the argument description below.
• Default values should be given (then=Stop.COAST).
• The return type should be given (-> int). When applicable, include the unit of the return value, so it becomes -> int: deg

Then follows a concise description of what this method, function, or class does.

Then follows a list of arguments:

• For each argument, include the expected type and unit if applicable, e.g. (int) or (Number, deg/s).
• Use Number when int and float are both allowed.
• If the description is long, use the indentation shown above.
• Make it readable. Instead of Union[float, SupportsFloat, complex, SupportsComplex], just say float or complex.

Then follows a description of the return value. The type is omitted here since it is already include in the docstring signature.

Development environment:

Prerequisites:

• VS Code (optional but recommended)
• Git
• Python 3
• Poetry

Information on installing prerequisites can be found on the pybricks-micropython contributor's guide.

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