Temp

circfirm/cli/path.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""CLI functionality for the paths subcommand.
+
+Author(s): Alec Delaney
+"""
+
+import click
+
+import circfirm
+
+
+@click.group()
+def cli() -> None:
+    """See filepaths for files and folders used by circfirm."""
+
+
+@cli.command(name="config")
+def path_config() -> None:
+    """Get the configuration settings filepath."""
+    click.echo(circfirm.SETTINGS_FILE)
+
+
+@cli.command(name="local-plugins")
+def path_local_plugins() -> None:
+    """Get the local plugins folder filepath."""
+    click.echo(circfirm.LOCAL_PLUGINS)
+
+
+@cli.command(name="archive")
+def path_archive() -> None:
+    """Get the firmware archive folder filepath."""
+    click.echo(circfirm.UF2_ARCHIVE)

docs/commands/path.rst

@@ -0,0 +1,44 @@
+..
+   SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+   SPDX-License-Identifier: MIT
+
+Viewing Important Filespaths
+============================
+
+You can see important filepaths used by ``circfirm`` using ``circfirm path``.
+
+See ``circfirm path --help`` and ``circfirm path [command] --help`` for more information on commands.
+
+Configuration Settings
+----------------------
+
+You can get the filepath of ``circfirm``'s configuration settings using ``circfirm path config``.
+
+.. note::
+
+    This is identical to the response given by ``circfirm config path``.
+
+.. code-block:: shell
+
+    # Get the configuration settings filepath
+    circfirm path config
+
+UF2 Archive
+-----------
+
+You can get the filepath of the UF2 archive folder using ``circfirm path archive``.
+
+.. code-block:: shell
+
+    # Get the UF2 archive folder filepath
+    circifrm path archive
+
+Local Plugins Folder
+--------------------
+
+You can get the filepath of the local plugins folder using ``circfirm path local-plugins``.
+
+.. code-block:: shell
+
+    # Get the local plugins folder filepath
+    circfirm path local-plugins

docs/index.rst

@@ -23,6 +23,7 @@
    commands/cache
    commands/query
    commands/config
+   commands/path
 
 .. toctree::
    :maxdepth: 2
@@ -36,9 +37,13 @@
    :caption: Plugins
    :hidden:
 
+   plugins/intro
+   plugins/create
+   plugins/example
+
 .. toctree::
    :maxdepth: 2
-   :caption: Examples
+   :caption: Example Scripts
    :hidden:
 
    examples/update_many

docs/plugins/create.rst

@@ -0,0 +1,25 @@
+..
+   SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+   SPDX-License-Identifier: MIT
+
+Creating Plugins
+================
+
+Creating a plugin is idnetical to creating other `click <https://click.palletsprojects.com>`_-based
+command line tools.  When ``circfirm`` is called from the command line, these command line tools
+are loaded and added as commands.
+
+Local Plugins
+-------------
+
+The easiest way to get started with creating plugins is to create a local plugin.  Local plugins
+reside in a designated folder next to where
+
+Downloadable Plugins
+--------------------
+
+Adding a Configuration File
+---------------------------
+
+Important Notes
+---------------

docs/plugins/example.rst

@@ -0,0 +1,6 @@
+..
+   SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+   SPDX-License-Identifier: MIT
+
+Example Plugin
+==============

docs/plugins/intro.rst

@@ -0,0 +1,85 @@
+..
+   SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+   SPDX-License-Identifier: MIT
+
+Introduction to Plugins
+=======================
+
+``circfirm`` can be extended through the use of its plugin system.  Plugins allow you
+to extend the CLI's capabilities beyond typical use cases and provided additional
+functionalities you may want to use.
+
+Below are general guidelines for downloading and configuring plugins, but see the
+plugin's documentation for additional details.
+
+Installing Plugins
+------------------
+
+Installing a plugin depends on how ``circfirm`` itself was installed.
+
+pipx
+^^^^
+
+If you installed ``circfirm`` via ``pipx``, you will need to "inject" the plugin
+into the same virtual environment as ``circfirm``.  This can typically be
+achieved used the ``inject`` command:
+
+.. code-block:: shell
+
+    # Inject circfirm-plugin-name for circfirm
+    pipx inject circfirm circfirm-plugin-name
+
+pip
+^^^
+
+If you installed ``circfirm`` via ``pip``, you can simply using the ``install``
+command to install the plugin into the same environment as ``circfirm``:
+
+.. code-block:: shell
+
+    # Install circfirm-plugin-name
+    pip install circfirm-plugin-name
+
+Activating Plugins
+------------------
+
+Activating a downloaded plugin can be done by adding an entry to the ``plugins.downloaded``
+confirguration for ``circfirm``:
+
+.. code-block:: shell
+
+    # Activate plugin_name
+    circfirm config add plugin_name
+
+Not that the plugin name may not exactly match the download name of the plugin.  The name
+added to ``plugins.downloaded`` should be a valid Python module import name - in fact, this
+is exactly what is happening behind the scenes!  Check with the plugin provider for exact
+details on what the plugin name is (as opposed to the download name).
+
+.. note::
+
+    This step is only needed if you downloaded the plugin.  Locally created plugins do not
+    require activation.
+
+Changing Configuration Settings
+-------------------------------
+
+Some plugins provide configuration files that can customize behavior similar to
+``circfirm``.  You can view, edit, and otherwise interact with these settings by
+using the ``--plugin`` option with the ``config`` command and it's various
+sub-commands:
+
+.. code-block:: shell
+
+    # View the settings for plugin_name
+    circfirm config view --plugin plugin_name
+
+    # Edit a setting for plugin_name
+    circfirm config edit --plugin plugin_name setting value
+
+    # Reset the settings for plugin_name
+    circfirm config reset --plugin plugin_name
+
+Note while, conventionally, a plugin will have a single configuration file, sharing the same
+name as the plugin, this may not be the case - it may use a different name or provide more
+than one configuration file.  Please check with the plugin provider for additional details.