From 7374b7ca1e06a710ba7091efcfee8c4a33b589a7 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Thu, 2 Jan 2025 08:52:06 -0500 Subject: [PATCH] Temp --- circfirm/cli/path.py | 35 +++++++++++++++ docs/commands/path.rst | 44 +++++++++++++++++++ docs/index.rst | 7 ++- docs/plugins/create.rst | 25 +++++++++++ docs/plugins/distribute.rst | 0 docs/plugins/example.rst | 6 +++ docs/plugins/intro.rst | 85 +++++++++++++++++++++++++++++++++++++ 7 files changed, 201 insertions(+), 1 deletion(-) create mode 100644 circfirm/cli/path.py create mode 100644 docs/commands/path.rst create mode 100644 docs/plugins/create.rst create mode 100644 docs/plugins/distribute.rst create mode 100644 docs/plugins/example.rst create mode 100644 docs/plugins/intro.rst diff --git a/circfirm/cli/path.py b/circfirm/cli/path.py new file mode 100644 index 0000000..5386b8b --- /dev/null +++ b/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) diff --git a/docs/commands/path.rst b/docs/commands/path.rst new file mode 100644 index 0000000..af7a362 --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index c959e3a..ea8bee9 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/plugins/create.rst b/docs/plugins/create.rst new file mode 100644 index 0000000..b6e814a --- /dev/null +++ b/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 `_-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 +--------------- diff --git a/docs/plugins/distribute.rst b/docs/plugins/distribute.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/plugins/example.rst b/docs/plugins/example.rst new file mode 100644 index 0000000..92a2ff7 --- /dev/null +++ b/docs/plugins/example.rst @@ -0,0 +1,6 @@ +.. + SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries + SPDX-License-Identifier: MIT + +Example Plugin +============== diff --git a/docs/plugins/intro.rst b/docs/plugins/intro.rst new file mode 100644 index 0000000..8c8c988 --- /dev/null +++ b/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.