diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ff19dde..ec3ac6f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,18 +4,18 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v5.0.0 hooks: - id: check-yaml - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.3.4 + rev: v0.11.13 hooks: - id: ruff-format - id: ruff args: ["--fix"] - repo: https://github.com/fsfe/reuse-tool - rev: v3.0.1 + rev: v5.0.2 hooks: - id: reuse diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3cd488c..2039e9c 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,4 +1,5 @@ # SPDX-FileCopyrightText: 2021 Melissa LeBlanc-Williams for Adafruit Industries +# SPDX-FileCopyrightText: Copyright (c) 2025 EGJ Moorington # # SPDX-License-Identifier: Unlicense @@ -13,6 +14,10 @@ build: tools: python: "3" +sphinx: + # Path to the Sphinx configuration file + configuration: docs/conf.py + python: install: - requirements: docs/requirements.txt diff --git a/README.rst b/README.rst index 55faf59..21401c7 100644 --- a/README.rst +++ b/README.rst @@ -153,3 +153,127 @@ Contributing Contributions are welcome! Please read our `Code of Conduct `_ before contributing to help this project stay welcoming. + +The easiest way to contribute to the repository is by `creating an issue `_. +Add a concise title and then explain the issue or suggestion in more detail in the description. This is helpful even if you do not intend to develop a fix. +If you wish to do so, however, the repository must first be forked. + +Forking the repository +---------------------- + +In order to add commits to this repository, it must be `forked `_ first. +This creates a copy of the repository you can edit. Make sure to deselect "Copy the ``main`` branch only". + +The following steps explain the recommended approach to working on a fork. Git needs to be installed for this. + +1. **Clone the repository.** + + Open a terminal in the directory where you wish to clone the fork, and then run the following: + + .. code-block:: shell + + git clone https://github.com//CircuitPython_Button_Handler.git + + Keep in mind the URL will be different if you changed the fork's name. + +2. **Set pre-commit up.** + + This repository is set up with tools that assist in development by automatically formatting code, enforcing code standards + and fixing issues where possible. + + For these tools to run automatically before committing, `pre-commit `_ + has to be installed. This can be done in a virtual environment in order to maintain a cleaner development setup. + Using a virtual environment isolates dependencies, ensuring they don't conflict with other projects. + + To install ``pre-commit`` in a Python virtual environment: + + 1. **Ensure Python is installed in your system.** + + You can check your version of `Python `_ + with the following command: + + .. code-block:: shell + + python --version + + 2. **Create a Python virtual environment.** + + To make a virtual environment of name ``.venv`` in the current directory, run: + + .. code-block:: shell + + python -m venv .venv + + 3. **Activate the virtual environment.** + + * On Windows, run: + + .. code-block:: shell + + .\.venv\Scripts\activate + + * On Linux or macOS, run: + + .. code-block:: shell + + source .venv/bin/activate + + To avoid repeating this step every time a terminal is opened in this directory, + configure your IDE to use the ``.venv`` virtual environment as the default interpreter. + In Visual Studio Code, this can be done by opening the command palette, typing + ``Python: Select Interpreter`` and selecting the ``.venv`` virtual environment. + + 4. **Install pre-commit.** + + This can easily be achieved by executing: + + .. code-block:: shell + + pip install pre-commit + pre-commit install + + After installing ``pre-commit``, the necessary hooks are installed on the next ``git commit`` + or the next time ``pre-commit run`` is executed. + +3. **Create a new branch.** + + To make a new branch from the ``dev`` branch: + + .. code-block:: shell + + git checkout dev + git branch -b + + **For consistency, please name the branch the same as the issue it addresses with the number of the issue preceding the name. + Write the name in** ``kebab-case`` **and with no special characters (underscores are allowed).** + + For example, the branch for `issue #26 `_ + "Update ``.readthedocs.yaml`` with Sphinx key" was "26-update-readthedocsyaml-with-sphinx-key". + +4. **Commit your changes.** + + After adding your changes, commit them to the new branch by executing: + + .. code-block:: shell + + git add . + git commit + + When ready, push the changes to GitHub with the following commands: + + .. code-block:: shell + + git remote add origin https://github.com//CircuitPython_Button_Handler.git + git push --set-upstream origin + +5. **Open a pull request.** + + Upon opening (or refreshing) the fork's GitHub page, a message should be visible close to the top of the page: + + This branch is 1 commit ahead of ``EGJ-Moorington/CircuitPython_Button_Handler:main``. + + Firstly, ensure the branch is up to date by pressing "Sync fork". Then, select "Contribute" > "Open pull request". + + The page will show "Open a pull request". Make sure to select ``base: dev`` and ``compare: `` in the dropdowns. + + Write a brief title and then explain the changes in the description. Finish by using a `closing keyword `_ for your issue. diff --git a/README.rst.license b/README.rst.license index 9da8584..d6884a9 100644 --- a/README.rst.license +++ b/README.rst.license @@ -1,3 +1,3 @@ SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries -SPDX-FileCopyrightText: Copyright (c) 2024 EGJ Moorington +SPDX-FileCopyrightText: Copyright (c) 2024, 2025 EGJ Moorington SPDX-License-Identifier: MIT diff --git a/button_handler.py b/button_handler.py index 7204c1c..b48d4cc 100644 --- a/button_handler.py +++ b/button_handler.py @@ -1,5 +1,5 @@ # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries -# SPDX-FileCopyrightText: Copyright (c) 2024 EGJ Moorington +# SPDX-FileCopyrightText: Copyright (c) 2024, 2025 EGJ Moorington # # SPDX-License-Identifier: MIT """ @@ -41,7 +41,7 @@ def ticks_ms() -> int: except ImportError: pass -__version__ = "3.0.0" +__version__ = "0.0.0+auto.0" __repo__ = "https://github.com/EGJ-Moorington/CircuitPython_Button_Handler.git" _TICKS_PERIOD = 1 << 29 @@ -102,7 +102,7 @@ def __init__( :value: max_multi_press = 2 The maximum amount of button presses that a multi-press can be. - :meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput` + :meth:`ButtonHandler.update` returns the appropriate multi-press :class:`ButtonInput` object immediaetly after the button has been pressed this many times. .. attribute:: multi_press_interval @@ -153,7 +153,7 @@ def __init__( :value: config.max_multi_press = 2 The maximum amount of button presses that a multi-press can be. - :meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput` + :meth:`ButtonHandler.update` returns the appropriate multi-press :class:`ButtonInput` object immediaetly after the button has been pressed this many times. .. attribute:: multi_press_interval @@ -333,20 +333,20 @@ def __init__( .. attribute:: button_number :type: int - :value: button_number = 0 + :value: 0 The index number of the button associated with the input. .. attribute:: callback :type: Callable[[], None] - :value: callback = lambda: None + :value: lambda: None The function to call when the input is detected - and returned by :meth:`ButtonHandler.update` + and returned by :meth:`ButtonHandler.update`. .. attribute:: timestamp :type: int - :value: timestamp = 0 + :value: 0 The timestamp (in milliseconds, provided by :meth:`supervisor.ticks_ms`) at which the input was performed. @@ -450,7 +450,7 @@ def __hash__(self) -> int: :return: The hash value of the input. :rtype: int - .. seealso:: :meth:`__eq__` - two :class:`ButtonInput` objects hash to the same value + .. seealso:: :meth:`__eq__` — two :class:`ButtonInput` objects hash to the same value if they are equal. """ return hash((self.action, self.button_number)) diff --git a/docs/conf.py b/docs/conf.py index cd51ff2..14a7ae6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,5 @@ # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries +# Copyright (c) 2025 EGJ Moorington # # SPDX-License-Identifier: MIT @@ -114,7 +115,7 @@ import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."] +# html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/ruff.toml b/ruff.toml index db37c83..3718816 100644 --- a/ruff.toml +++ b/ruff.toml @@ -1,4 +1,5 @@ # SPDX-FileCopyrightText: 2024 Tim Cocks for Adafruit Industries +# SPDX-FileCopyrightText: Copyright (c) 2025 EGJ Moorington # # SPDX-License-Identifier: MIT @@ -16,7 +17,7 @@ extend-select = [ "PLC2401", # non-ascii-name "PLC2801", # unnecessary-dunder-call "PLC3002", # unnecessary-direct-lambda-call - "E999", # syntax-error +# "E999", # syntax-error "PLE0101", # return-in-init "F706", # return-outside-function "F704", # yield-outside-function