[sail3r]

Hi @anurag3301

First to thank you for still maintaining the repo, and second for creating it. Used it last year to create a wonderful autopilot in ESP32 and am just now starting another v2 version.

Made one reasonable implementation and also refactor README.md which was a little sparse and obscure. Made the configs Lazy centered, hope that's ok.

This PR

A new setup option, project_only (default false).

When it is true, the menu_key which-key menu is attached only to buffers
whose file is inside a PlatformIO project. "Inside" means platformio.ini
exists in the file's directory or in any parent directory, so a file deep in
src/ counts. A buffer with no file name is checked against the current
working directory.

When it is false nothing changes: the menu is mapped globally, as before.

require('platformio').setup({
  menu_key = '<leader>\\',
  project_only = true,
})

How it works

• The menu is added with which-key's buffer option, so the mappings belong
  to that one buffer and nowhere else.
• Every time you enter a buffer, the plugin checks it. It also checks the
  buffer you are in when setup() runs, because with lazy loading that
  buffer was already entered before the plugin existed.
• Help, terminal and other special buffers are skipped.
• A buffer that already got the menu is remembered (b:platformio_menu),
  so the menu is not added twice. Buffers outside a project are re-checked
  each time you enter them, so a project created later with :Pioinit is
  picked up.
• The search for platformio.ini is the same one the commands already use.
  It now lives in its own function, find_platformioRootDir(), which does
  not show the "Could not find platformio.ini" error and does not change
  vim.g.platformioRootDir. The commands behave exactly as before.

Things worth knowing

• With project_only = true, load the plugin when a file opens, e.g.
  lazy.nvim event = { 'BufReadPost', 'BufNewFile' }. Lazy-loading on the
  menu key with keys would put a global stub mapping in every buffer,
  which defeats the option.
• The :Pio* commands stay available everywhere; only the menu is limited.
• Small internal fix needed for this: which-key empties the table you pass
  to wk.add(), so the menu table is now built fresh for every call instead
  of being one shared module-level table.
• The menu icon is now written as a byte escape. It is the same character
  at runtime; the source just stays plain ASCII.

README

The README is rewritten around one lazy.nvim spec. Nothing in it is new
behaviour; it describes what the code already does.

• Introduction after the demo video: what PlatformIO is and what the
  plugin gives you inside Neovim.
• Requirements, worked out from the code rather than copied from the
  old list:
  • toggleterm.nvim is the only hard requirement. Every command that runs
    pio opens a toggleterm terminal.
  • plenary.nvim is only needed for :Piolib, and which-key.nvim only when
    menu_key is set.
  • No picker plugin is needed. Without one, Neovim's own vim.ui.select
    is used. Telescope, snacks.picker and mini.pick are optional, and are
    shown commented out with what each one needs to work.
  • nvim-treesitter and telescope-ui-select.nvim were listed before, but
    the plugin never uses them, so they are gone.
  • Neovim 0.12, because :PioLSP uses :lsp restart and JSON
    formatting options that only exist from 0.12.
• Installation is now a single spec with every option in opts, shown
  with its default and a one-line explanation. This replaces the separate
  vim.g.pioConfig snippet.
• Keybindings holds the default menu tree and the keys inside PIO
  terminals. Lazy loading shows a cmd + keys setup, and a cmd +
  event setup for project_only.
• The old "Lazy::cond" section is removed; project_only covers what it
  was for. Its snippet also had a typo (plguins) that made lazy.nvim
  restore every installed plugin instead of just this one.
• A script checks the README against the code: every Lua block runs, the
  options pass the real setup(), the menu tree equals the built-in
  default, and the command lists match the commands the plugin defines.
  markdownlint passes apart from the long logo line at the top.

Testing

It was tested by hand: menu shows up only in project buffers with
project_only = true, and everywhere with false.

Also checked with stylua (--check .) and a script that runs the real setup() and which-key's real mapping parser against fake files and buffers (default mode, project and non-project buffers, nested directories, special buffers, invalid option value, and that the old root-directory lookup still behaves the same).

Cheers, and thank you again :))