update docs

.scripts/link_doxygen_sphinx.py

@@ -15,14 +15,14 @@ def create_rst_file(src_path, dest_path):
         rst_file.write(f'   :project: LcdMenu\n')
 
 def create_index_file(directory, entries, subdirs, is_root=False):
-    dir_name = os.path.basename(directory) if not is_root else "Class reference"
+    dir_name = os.path.basename(directory) if not is_root else "API reference"
     index_path = os.path.join(directory, 'index.rst')
     with open(index_path, 'w') as index_file:
         index_file.write(f'{dir_name}\n')
         index_file.write(f'{"=" * len(dir_name)}\n\n')
         if is_root:
             index_file.write('.. rst-class:: lead\n\n')
-            index_file.write('This section contains the class reference documentation for the |project| library.\n')
+            index_file.write('This section contains the API reference documentation for the |project| library.\n')
             index_file.write('Here you will find detailed descriptions of all the classes, their methods, and attributes.\n\n')
             index_file.write('-'*80)
             index_file.write('\n\n')

.scripts/version.py

@@ -13,14 +13,19 @@ def build(files, version):
         data = ''
         separator = ''
         if file.endswith('.json'): separator = ": "
+        elif file.endswith('.rst'): separator = '^'
         else: separator = '='
 
         with open(file, "r") as a_file:
             for line in a_file:
                 stripped_line = line.strip()
                 key = stripped_line.split(separator, 1)[0]
 
-                if re.search("version", key) != None:
+
+                if separator == '^' and re.search("forntoh/LcdMenu", key) != None:
+                    spaces = len(line) - len(line.lstrip())
+                    data+=(' ' * spaces + key + separator + version + '\n')
+                elif re.search("version", key) != None:
                     anchor = ''
                     suffix = ''
                     prefix = ''

docs/source/index.rst

@@ -1,3 +1,5 @@
+.. _welcome:
+
 Welcome to the |project| Docs!
 ===============================
 
@@ -54,6 +56,7 @@ including LCD displays and OLED displays *(coming soon)*.
     :hidden:
 
     overview/getting-started
+    overview/deep-dive/index
 
 .. toctree::
     :maxdepth: 2

docs/source/overview/deep-dive/basic.rst

@@ -0,0 +1,21 @@
+Basic menu item
+---------------
+
+The basic menu item is a simple menu item that displays a text label on the screen.
+It does not have any special behavior other than being selectable by the user.
+It behaves like a placeholder and has no associated action or behavior.
+
+The basic menu item is useful for creating simple menu structures with static text labels.
+
+A basic menu item can be created using the following syntax:
+
+.. code-block:: cpp
+
+    ITEM_BASIC("Item 1")
+
+This is how a basic menu item is rendered on a 16x2 LCD screen:
+
+.. image:: images/item-basic.png
+    :alt: Basic menu item
+
+Find more information about the basic menu item in the :doc:`API reference </reference/api/MenuItem>`.

docs/source/overview/deep-dive/command.rst

@@ -0,0 +1,53 @@
+Command menu item
+-----------------
+
+The command menu item is a menu item that executes a function when selected by the user.
+It is useful for creating menu items that perform a specific action when selected.
+
+This can be used in various scenarios, such as:
+
+- Controlling a device or sensor (e.g., turning on a motor)
+- Changing a setting or configuration (e.g. saving a setting/value)
+- Triggering an event or action (e.g., sending a message)
+
+How to create a command menu item
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A command menu item can be created using the following syntax:
+
+.. tab-set::
+
+    .. tab-item:: As a lambda function
+
+        .. code-block:: cpp
+
+            ITEM_COMMAND("Item 1", []() {
+                // Function body
+            })
+
+    .. tab-item:: As a function pointer
+
+        .. code-block:: cpp
+
+            // Function definition
+            void myFunction() {
+                // Function body
+            }
+            // Create a command menu item
+            ITEM_COMMAND("Item 1", myFunction)
+
+Let's take a look at an example of a command menu item that simply prints a message to the serial monitor when selected:
+
+.. code-block:: cpp
+
+    ITEM_COMMAND("Print Message", []() {
+        Serial.println("Hello, world!");
+    })
+
+When the "Print Message" menu item is selected, the message "Hello, world!" will be printed to the serial monitor.
+
+.. code-block:: console
+
+    $ Hello, world!
+
+Find more information about the command menu item in the :doc:`API reference </reference/api/ItemCommand>`.

docs/source/overview/deep-dive/index.rst

@@ -0,0 +1,24 @@
+Deep Dive
+=========
+
+Let's dive deep into the details of the system.
+
+The first thing you need to know is that the system is built around the concept of a menu screen.
+A menu screen is a collection of menu items that are displayed on the screen.
+Each menu item can be selected and interacted with by the user.
+
+The system provides a number of built-in menu items that you can use to create your menu structure.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Here are some of the built-in menu items:
+
+    basic
+    command
+    submenu
+    toggle
+    value
+    list
+    custom
+
+You can also create your own custom menu items by extending the base menu item class.

docs/source/overview/getting-started.rst

@@ -12,7 +12,7 @@ various helpers for handling user input like rotary encoders and buttons.
 Installation
 ------------
 
-Follow this guide to install the library with **Arduino Library Manager** or install it with **PlatformIO** using the steps below:
+Follow `this guide <https://www.ardu-badge.com/LcdMenu>`_ to install the library with **Arduino Library Manager** or install it with **PlatformIO** using the steps below:
 
 1. Open the PlatformIO IDE or VSCode with PlatformIO extension installed.
 
@@ -23,8 +23,50 @@ Follow this guide to install the library with **Arduino Library Manager** or ins
     .. code-block:: bash
     
         lib_deps =
-            forntoh/LcdMenu@^4.0.0
+            forntoh/LcdMenu@^5.0.0
 
 4. Save the changes to the platformio.ini file.
 
-5. Build and upload your project to your device.
+5. Build and upload your project to your device.
+
+Usage
+-----
+
+To create a menu system with |project|, you need to define a menu structure and a display interface and an input method to interact with the menu.
+For this example, we will use the ``LiquidCrystal_I2C`` display interface and ``KeyboardAdapter`` for user input to read from the serial monitor.
+You can replace these with other display interfaces and input methods as needed or create your own.
+
+.. code-block:: cpp
+
+    #include <LcdMenu.h>
+    #include <MenuScreen.h>
+    #include <display/LiquidCrystal_I2CAdapter.h>
+    #include <input/KeyboardAdapter.h>
+
+    MENU_SCREEN(mainScreen, mainItems,
+        ITEM_BASIC("Item 1"),
+        ITEM_BASIC("Item 2"),
+        ITEM_BASIC("Item 3"),
+        ITEM_BASIC("Item 4"));
+
+    LiquidCrystal_I2C lcd(0x27, 16, 2);
+    LiquidCrystal_I2CAdapter lcdAdapter(&lcd, 16, 2);
+    LcdMenu menu(lcdAdapter);
+    KeyboardAdapter keyboard(&menu, &Serial);
+
+    void setup() {
+        Serial.begin(9600);
+        lcdAdapter.begin();
+        menu.setScreen(mainScreen);
+    }
+
+    void loop() {
+        keyboard.observe();
+    }
+
+This example creates a simple menu with four items and displays it on a 16x2 LCD screen.
+The menu is controlled using the serial monitor, where you can navigate through the items using the arrow keys.
+
+For detailed information on how to use |project|, check out the :doc:`API Reference </reference/api/index>`.
+
+In the next chapter, we will go through the different components of the library and how to use them to create more complex menu systems.

version

@@ -62,6 +62,7 @@ if [[ "$part_to_increment" =~ ^[1-3]$ ]]; then
     fi
     # Update version
     python3 .scripts/version.py library.* $incremented_version
+    python3 .scripts/version.py docs/source/overview/getting-started.rst $incremented_version
     # Update keywords
     python3 .scripts/keywords.py src/*.h src/**/*.*
     # Update Bug Report Template