Merge pull request #70 from tekktrik/dev/docs

Add documentation

Makefile

@@ -45,9 +45,9 @@ endif
 
 .PHONY: test
 test:
-	-@${MAKE} test-prep --no-print-directory
-	-@${MAKE} test-run --no-print-directory
-	-@${MAKE} test-clean --no-print-directory
+	-@"${MAKE}" test-prep --no-print-directory
+	-@"${MAKE}" test-run --no-print-directory
+	-@"${MAKE}" test-clean --no-print-directory
 
 .PHONY:
 test-run:

circfirm/backend/github.py

@@ -55,7 +55,7 @@ def get_rate_limit() -> Tuple[int, int, datetime.datetime]:
     return available, total, reset_time
 
 
-def get_board_list(token: str) -> List[str]:
+def get_board_id_list(token: str) -> List[str]:
     """Get a list of CircuitPython boards."""
     boards = set()
     headers = BASE_REQUESTS_HEADERS.copy()

circfirm/cli/current.py

@@ -30,8 +30,8 @@ def cli() -> None:
     """Check the information about the currently connected board."""
 
 
-@cli.command(name="id")
-def current_id() -> None:
+@cli.command(name="board-id")
+def current_board_id() -> None:
     """Get the board ID of the currently connected board."""
     click.echo(get_board_info()[0])
 

circfirm/cli/query.py

@@ -23,9 +23,9 @@ def cli():
     """Query things like latest versions and board lists."""
 
 
-@cli.command(name="boards")
+@cli.command(name="board-ids")
 @click.option("-r", "--regex", default=".*", help="Regex pattern to use for board IDs")
-def query_boards(regex: str) -> None:
+def query_board_ids(regex: str) -> None:
     """Query the local CircuitPython board list."""
     settings = circfirm.cli.get_settings()
     gh_token = settings["token"]["github"]
@@ -41,11 +41,11 @@ def query_boards(regex: str) -> None:
         if do_output:
             boards = circfirm.cli.announce_and_await(
                 "Fetching boards list",
-                circfirm.backend.github.get_board_list,
+                circfirm.backend.github.get_board_id_list,
                 args=(gh_token,),
             )
         else:
-            boards = circfirm.backend.github.get_board_list(gh_token)
+            boards = circfirm.backend.github.get_board_id_list(gh_token)
     except ValueError as err:
         raise click.ClickException(err.args[0])
     except requests.ConnectionError as err:
@@ -54,7 +54,7 @@ def query_boards(regex: str) -> None:
         )
     for board in boards:
         board_id = board.strip()
-        result = re.match(regex, board_id)
+        result = re.search(regex, board_id)
         if result:
             click.echo(board_id)
 

docs/commands/cache.rst

@@ -4,3 +4,45 @@
 
 Caching Versions
 ================
+
+You can interact with the local cache of CircuitPython firmware versions using ``circfirm cache``.
+
+See ``circfirm cache --help`` and ``circfirm cache [command] --help`` for more information on commands.
+
+Saving Versions
+---------------
+
+You can save versions of the CircuitPython firmware using ``circfirm cache save``.
+
+.. code-block:: shell
+
+    # Save the CircuitPython 8.0.0 firmware for the feather_m4_express board
+    circfirm cache save feather_m4_express 8.0.0
+
+Listing Versions
+----------------
+
+You can list cached versions of the CircuitPython firmware using ``circfirm cache list``.
+
+.. code-block:: shell
+
+    # List all the firmware versions
+    circfirm cache list
+
+    # List all the firmware versions for the feather_m4_express board
+    circfirm cache list --board-id feather_m4_express
+
+Clearing the Cache
+------------------
+
+You can clearr cached firmware versions using ``circfirm cache clear``.
+
+You can also specify what should be cleared in terms of board IDs, versions, and languages.
+
+.. code-block:: shell
+
+    # Clear the cache
+    circfirm cache clear
+
+    # Clear the cache of French versions of the feather_m4_express
+    circfirm cache clear --board-id feather_m4_express --language fr

docs/commands/config.rst

@@ -4,3 +4,44 @@
 
 Configuring the CLI
 ===================
+
+You can modify the CLI configurations settings using ``circfirm config``.
+
+See ``circfirm config --help`` and ``circfirm config [command] --help`` for more information on commands.
+
+View Settings
+-------------
+
+You can view configuration settings using ``circfirm config view``.
+
+You can view all the settings, a subset, or just a specific one.  Subsettings are accessed using period separators.
+
+.. code-block:: shell
+
+    # View all the configuration settings
+    circfirm config view
+
+    # View a specific setting
+    circfirm config view output.supporting.silence
+
+Edit Settings
+-------------
+
+You can edit configuration settings using ``circfirm config view``.
+
+You must edit a specific setting at a time.  Subsettings are accessed using period separators.
+
+.. code-block:: shell
+
+    # Edit a configuration settings with a value
+    circfirm config edit output.supporting.silence true
+
+Reset Settings
+--------------
+
+You can reset the configuration settings to the default using ``circfirm config reset``.
+
+.. code-block:: shell
+
+    # Reset the configuration settings to the default
+    circfirm config reset

docs/commands/current.rst

@@ -4,3 +4,27 @@
 
 Checking the Current Version
 ============================
+
+You can get information about a currently connected board using ``circfirm current``.
+
+See ``circfirm current --help`` and ``circfirm current [command] --help`` for more information on commands.
+
+Getting the Board ID
+--------------------
+
+You can get the board ID of the currently connected board using ``circfirm current board-id``.
+
+.. code-block:: shell
+
+    # Get the board ID of the connected board
+    circfirm current board-id
+
+Getting the Firmware Version
+----------------------------
+
+You can get the CircuitPython version of the currently connected board using ``circfirm current version``.
+
+.. code-block:: shell
+
+    # Get the firmware version of the connected board
+    circfirm current verson

docs/commands/install.rst

@@ -4,3 +4,28 @@
 
 Installing Specific Versions
 ============================
+
+You can install different CircuitPython versions to a connected board using ``circfirm install``.
+
+See ``circfirm install --help`` for more information.
+
+The board should be connected so it shows up as a CIRCUITPY USB drive (or equivalently named),
+where the board ID will be read from the ``boot_out.txt`` file.  The CLI will then prompt you to set the
+board into bootloader mode, after which the selected CircuitPython version will be installed on
+the board.
+
+If you wish to skip the step where the board ID is collected and simply connected the board in
+bootloader mode, you can do so and simply use the ``--board-id`` option to provide the board ID.
+
+You can specify a language using the ``--language`` option - the default is US English.
+
+.. code-block:: shell
+
+    # Install CircuitPython 8.0.0 on the connected board
+    circfirm install 8.0.0
+
+    # Install the French translation of CircuitPython on the connected board
+    circfirm install 8.0.0 --language fr
+
+    # Install CircuitPython 8.0.0 on the connected Adafruit QT Py ESP32 Pico (in bootloader mode)
+    circfirm install 8.0.0 --board-id adafruit_qtpy_esp32_pico

docs/commands/query.rst

@@ -4,3 +4,79 @@
 
 Querying Boards and Versions
 ============================
+
+You can query for valid board IDs and CircuitPython versions from online resources using ``circfirm query``.
+
+See ``circfirm query --help`` and ``circfirm query [command] --help`` for more information on commands.
+
+Querying Board IDs
+------------------
+
+You can query a list of valid board IDs from the CircuitPython GitHub repository using ``circfirm query board-ids``.
+
+You can use the ``--regex`` option to further select boards from the list matching a provided regex pattern.
+The pattern will be searched for **ANYWHERE** in the board ID (e.g., "hello" **would** match "123hello123") unless
+the pattern specifies otherwise.
+
+.. note::
+
+    Querying board IDs communicates with GitHub, which can only be done 60 times per hour unauthenticated.
+    If you plan to make frequent use of this command consider adding a GitHub token to the configuration
+    settings (``circfirm config edit token.github <your-token-here>``).
+
+.. code-block:: shell
+
+    # List all board IDs
+    circfirm query board-ids
+
+    # List all board IDs containing the phrase "pico"
+    circfirm query board-ids --regex pico
+
+Querying Board Versions
+-----------------------
+
+You can query a list of CircuitPython versions for a board ID in the official AWS S3 bucket of firmware
+using ``circfirm query version``.
+
+You can use the ``--regex`` option to further select versions from the list matching a provided regex pattern.
+The pattern will be searched for **FROM THE BEGINNING** in the board ID (e.g., "hello" **would not**  match "123hello123").
+This is done to make matching entire version sets more convenient ("8\.2\..+" matches the entirety of 8.2 and all associated
+minor, alpha, beta and release candidate versions).
+
+You can also set the language using the ``--language`` option, which can affect the list of available versions.
+
+.. code-block:: shell
+
+    # List all available versions for the Feather M4 Express
+    circfirm query versions feather_m4_express
+
+    # List all available French versions for the Feather M4 Express
+    circfirm query versions feather_m4_express --language fr
+
+    # List all versions in the 8.2.X set for the Feather M4 Express
+    circfirm query versions feather_m4_express --regex 8\.2\..+
+
+Query the Latest Version
+------------------------
+
+You can query the latest version of CircuitPython use ``circfirm query latest``
+
+This command take a board ID as an argument, as this may have an effect on available CircuitPython versions.
+For simplicity, if information is not needed about a specific board but rather the CircuitPython project as
+a whole, the default board ID ``raspberry_pi_pico`` is used, as it is an actively supported board.
+
+You can also set the language using the ``--language`` option, which can affect the list of available versions.
+
+If you would like to include pre-release versions as potential latest versions, you can use the
+``--pre-release`` flag.
+
+.. code-block:: shell
+
+    # Get the latest version of CircuitPython
+    circfirm query latest
+
+    # Get the latest version of CircuitPython for the Feather M4 Express
+    circfirm query latest feather_m4_express
+
+    # Get the latest version of CircuitPython for the Feather M4 Express, including pre-releases
+    circfirm query latest feather_m4_express --pre-release

docs/commands/update.rst

@@ -4,3 +4,39 @@
 
 Updating to the Latest Version
 ==============================
+
+You can update the CircuitPython version of a connected board using ``circfirm update``.
+
+See ``circfirm update --help`` for more information.
+
+The board should be connected so it shows up as a CIRCUITPY USB drive (or equivalently named),
+where the board ID will be read from the ``boot_out.txt`` file.  The CLI will then prompt you to set the
+board into bootloader mode, after which the selected CircuitPython version will be installed on
+the board.
+
+If you wish to skip the step where the board ID is collected and simply connected the board in
+bootloader mode, you can do so and simply use the ``--board-id`` option to provide the board ID.
+
+You can specify a language using the ``--language`` option - the default is US English.
+
+If you would like to include pre-releases as potential update versions, you can use the
+``--pre-release`` flag.
+
+.. note::
+
+    This command will not update the board if the detected version of CircuitPython on the connected
+    board is greater than or equal to updated version.
+
+.. code-block:: shell
+
+    # Update CircuitPython on the connected board
+    circfirm update
+
+    # Update the French translation of CircuitPython on the connected board
+    circfirm --language fr
+
+    # Update CircuitPython 8.0.0 on the connected Adafruit QT Py ESP32 Pico (in bootloader mode)
+    circfirm update --board-id adafruit_qtpy_esp32_pico
+
+    # Update CircuitPython on the connected board, considering pre-release versions
+    circfirm update --pre-release

docs/infrastructure/ci.rst

@@ -4,3 +4,39 @@
 
 CI/CD Pipeline
 ==============
+
+.. _build-ci:
+
+Build CI
+--------
+
+When code is pushed to the repository or a pull request is submitted, it will
+trigger a GitHub Actions run of the build CI, which can be found in
+``.github/workflows/push.yml``.  This build CI performs the following checks:
+
+- Code quality
+- Packaging build
+- Code testing
+- Code coverage
+
+You can read more about the code checks performed :doc:`here <codecheck>`
+
+CodeQL CI
+---------
+
+Similar to the build CI, a GitHub Actions performs a CodeQL check on the code
+whenever code is pushed to the repository or a pull request is submitted.
+Additionally, it runs this action daily to ensure best practices and look for
+issues as CodeQL is improved.
+
+.. _publish-ci:
+
+Publish CI
+----------
+
+When a release is made on GitHub for the project, it builds the project using
+the Python ``build`` package.  Before building, the publish CI pushes the
+release tag to the ``VERSION`` file.  The CI then uses ``build`` to generate
+both source and binary distributions of the project.  The CU then uploads
+these distributions to PyPI for download through tools such as ``pipx`` and
+``pip``.