docs: Update autocomplete docs for click-based CLI

peterdragun · peterdragun · commit 89cfa5231ea7 · 2025-02-27T11:54:09.000+01:00
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -527,9 +527,8 @@ build_docs:
       - docs/_build/*/*/html/*
     expire_in: 4 days
   script:
-    - pip install .  # esptool is needed for the automatic API documentation generation
+    - pip install ".[docs]" --prefer-binary  # esptool is needed for the automatic API documentation generation
     - cd docs
-    - pip install -r requirements.txt --prefer-binary
     - build-docs -l en -t {esp8266,esp32,esp32s2,esp32c3,esp32s3,esp32c2,esp32c6,esp32h2,esp32p4,esp32c5,esp32c61}
 
 .deploy_docs_template:
@@ -543,7 +542,7 @@ build_docs:
     - source ${CI_PROJECT_DIR}/docs/utils.sh
     - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
     - export GIT_VER=$(git describe --always)
-    - pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt --prefer-binary
+    - pip install ".[docs]" --prefer-binary
     - deploy-docs
 
 deploy_docs_preview:
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -29,8 +29,11 @@
     "esp_docs.esp_extensions.dummy_build_system",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx_tabs.tabs",
 ]
 
+sphinx_tabs_disable_tab_closing = True
+
 ESP8266_DOCS = []
 
 ESP32_DOCS = [
diff --git a/docs/en/esptool/advanced-commands.rst b/docs/en/esptool/advanced-commands.rst
@@ -133,6 +133,18 @@ The Serial Flash Discoverable Parameters (SFDP) store essential vendor-specific
 
 This will read 4 bytes from SFDP address 16.
 
+.. only:: not esp8266 and not esp32
+
+    Read Security Info: ``get_security_info``
+    ------------------------------------------
+
+    The ``get_security_info`` command allows you to read security-related information (secure boot, secure download, etc.) about the Espressif devices.
+
+    ::
+
+        esptool.py get_security_info
+
+
 .. only:: esp8266
 
     .. _chip-id:
diff --git a/docs/en/installation.rst b/docs/en/installation.rst
@@ -69,44 +69,76 @@ If updating directly is unavoidable, make sure you update to a compatible versio
 
    $ pip install "esptool<4"
 
+.. _shell-completion:
+
 Shell Completions
 -----------------
 
 To activate autocompletion, you can manually add commands provided below to your shell's config file
 or run them in your current terminal session for one-time activation.
 You will likely have to restart or re-login for the autocompletion to start working.
 
-Bash
-^^^^
+.. tabs::
 
-::
+   .. group-tab:: Bash
 
-   eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
+      .. tabs::
 
-Zsh
-^^^
+         .. group-tab:: v5
 
-To activate completions in zsh, first make sure `compinit` is marked for
-autoload and run autoload:
+            .. code-block:: bash
 
-.. code-block:: bash
+               eval "$(_ESPTOOL_PY_COMPLETE=bash_source esptool.py espsecure.py espefuse.py)"
 
-   autoload -U compinit
-   compinit
+         .. group-tab:: v4
 
-Afterwards you can enable completions for esptool.py, espsecure.py and espefuse.py:
+            .. code-block:: bash
 
-::
+               eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
 
-   eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
+   .. group-tab:: Zsh
 
-Fish
-^^^^
+      To activate completions in zsh, first make sure `compinit` is marked for
+      autoload and run autoload:
 
-Not required to be in the config file, only run once
+      .. code-block:: bash
 
-::
+         autoload -U compinit
+         compinit
+
+      Afterwards you can enable completions for esptool.py, espsecure.py and espefuse.py:
+
+      .. tabs::
+
+         .. group-tab:: v5
+
+            .. code-block:: bash
+
+               eval "$(_ESPTOOL_PY_COMPLETE=zsh_source esptool.py espsecure.py espefuse.py)"
+
+         .. group-tab:: v4
+
+            .. code-block:: bash
+
+               eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)"
+
+   .. group-tab:: Fish
+
+      .. tabs::
+
+         .. group-tab:: v5
+
+            .. code-block:: bash
+
+               _ESPTOOL_PY_COMPLETE=fish_source esptool.py espsecure.py espefuse.py | source
+
+         .. group-tab:: v4
+
+            Not required to be in the config file, only run once
+
+            .. code-block:: bash
+
+               register-python-argcomplete --shell fish esptool.py espsecure.py espefuse.py >~/.config/fish/completions/esptool.py.fish
 
-   register-python-argcomplete --shell fish esptool.py espsecure.py espefuse.py >~/.config/fish/completions/esptool.py.fish
 
 Other shells nor OS Windows are not supported.
diff --git a/docs/en/migration-guide.rst b/docs/en/migration-guide.rst
@@ -118,3 +118,38 @@ All command functions (e.g., ``verify_flash``, ``write_flash``) have been refact
 3. Test your updated scripts to ensure compatibility with the new API.
 
 For detailed examples and API reference, see the :ref:`scripting <scripting>` section.
+
+
+Flash Operations from Non-flash Related Commands
+************************************************
+
+When esptool is used as a CLI tool, the following commands no longer automatically attach the flash by default, since flash access is not required for their core functionality:
+
+- ``load_ram``
+- ``read_mem``
+- ``write_mem``
+- ``dump_mem``
+- ``chip_id``
+- ``read_mac``
+
+The ``--spi-connection`` CLI argument has been **removed** from non-flash related commands in v5. This argument had no effect on the command execution. Affected commands:
+
+- ``elf2image``
+- ``merge_bin``
+
+**Migration Steps:**
+
+1. Update any scripts that attempt to attach flash from non-flash related commands.
+2. If you need to attach flash for above mentioned commands, use the ``attach_flash`` function from the public API instead. For more details see :ref:`scripting <scripting>`.
+3. Remove the ``--spi-connection`` argument from ``elf2image`` and ``merge_bin`` commands.
+
+
+Shell Completion
+****************
+
+The esptool ``v5`` has switched to using `Click <https://click.palletsprojects.com/>`_ for command line argument parsing, which changes how shell completion works.
+
+**Migration Steps:**
+
+1. Remove the old shell completion code from your scripts and shell configuration files like ``.bashrc``, ``.zshrc``, ``.config/fish/config.fish``, etc.
+2. Follow the new shell completion setup instructions in the :ref:`shell-completion` section of the :ref:`installation <installation>` guide.
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/esptool/__init__.py b/esptool/__init__.py
@@ -366,12 +366,12 @@ def cli(
     ctx.obj.update(kwargs)
     ctx.obj["invoked_subcommand"] = ctx.invoked_subcommand
     ctx.obj["esp"] = getattr(ctx, "esp", None)
+    log.print(f"esptool.py v{__version__}")
+    load_config_file(verbose=True)
 
 
 def prepare_esp_object(ctx):
     """Prepare ESP object for operation"""
-    log.print(f"esptool.py v{__version__}")
-    load_config_file(verbose=True)
     StubFlasher.set_preferred_stub_subdir(ctx.obj["stub_version"])
     # Commands that require an ESP object (flash read/write, etc.)
     # 1) Get the ESP object
diff --git a/pyproject.toml b/pyproject.toml
@@ -59,6 +59,10 @@
         "commitizen",
     ]
     hsm = ["python-pkcs11"]
+    docs = [
+        "esp-docs~=1.10",
+        "sphinx-tabs",
+    ]
 
 [tool.setuptools]
     include-package-data = true
