Merge branch 'docs/fix-grammar' into 'main'

docs: improve grammar and clarity in documentation and code comments

Closes PACMAN-1047

See merge request espressif/idf-component-manager!497

Author: kumekay

docs/README.md

@@ -2,19 +2,28 @@
 
 To build documentation locally, run these command from the root of the project
 
-Install dependencies:
+1. Install dependencies:
 
 ```sh
 pip install .[docs]
 ```
 
-Build the docs:
+Install the project in **development mode**:
+
+```sh
+$ pip install -e .
+```
+
+More details on development mode can be found here:
+https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+
+2. Build the docs:
 
 ```sh
 sphinx-build docs/en docs/html_output
 ```
 
-Preview in the browser:
+3. Preview in the browser:
 
 ```sh
 python -m webbrowser -t "file://$(pwd)/docs/html_output/index.html"

docs/en/conf.py

@@ -12,5 +12,5 @@
 compote_cli = initialize_cli()
 
 project = 'IDF Component Management'
-copyright = '2023, Espressif Systems (Shanghai) Co., Ltd.'
+copyright = '2023-2025, Espressif Systems (Shanghai) Co., Ltd.'
 language = 'en'

docs/en/getting_started/index.rst

@@ -2,13 +2,13 @@
  Getting Started
 #################
 
-The IDF Component Manager is included and enabled by default in all `supported ESP-IDF <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html>`_ versions.
+The IDF Component Manager comes pre-installed and enabled by default in all `supported ESP-IDF versions <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html>`_.
 
 ********************************************
  Checking the IDF Component Manager Version
 ********************************************
 
-If you are unsure which version of the IDF Component Manager is included in your ESP-IDF installation, you can find out by running a CLI command.
+If you're unsure which version of the IDF Component Manager is included in your ESP-IDF installation, you can check it using a CLI command.
 
 First, activate the `ESP-IDF environment <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#installation>`_, then run the help command:
 
@@ -18,7 +18,7 @@ First, activate the `ESP-IDF environment <https://docs.espressif.com/projects/es
 
       Windows
 
-      Run ``ESP-IDF PowerShell Environment`` or ``ESP-IDF Command Prompt (cmd.exe)`` from the Start menu and run the following command:
+      Open ``ESP-IDF PowerShell Environment`` or ``ESP-IDF Command Prompt (cmd.exe)`` from the Start menu and run the following command:
 
       .. code:: powershell
 
@@ -42,4 +42,4 @@ First, activate the `ESP-IDF environment <https://docs.espressif.com/projects/es
          $ . $IDF_PATH/export.fish
          $ compote version
 
-Older versions of the component manager may not include the ``compote version`` command. If the command is not available in your IDF Component Manager, please consider upgrading it to the latest version. See `Upgrading the IDF Component Manager <#installing-and-upgrading-the-idf-component-manager>`_.
+If you're using an older version of the Component Manager, the ``compote version`` command might not be available. In that case, consider upgrading to the latest version. For details, see `Upgrading the IDF Component Manager <#installing-and-upgrading-the-idf-component-manager>`_.

docs/en/guides/packaging_components.rst

@@ -6,7 +6,7 @@
 
    This feature is available in version 2.1 and later.
 
-A partial mirror contains only a subset of the components available in the main mirror. This can be useful when you have limited network connectivity or bandwidth, or when you want to restrict the versions of components available to your developers.
+A partial mirror contains only a subset of the components available in the main mirror. This is useful when you have limited network connectivity or bandwidth, or when you want to restrict which versions of components are available to your developers.
 
 ******************************
  Sync from Component Registry
@@ -18,68 +18,68 @@ To sync from the component registry, use the following command:
 
    compote registry sync --component <component> /path/to/mirror
 
-For example, to sync the ``example/cmp`` component, use the following command:
+For example, to sync the ``example/cmp`` component, use the command:
 
 .. code:: shell
 
    compote registry sync --component example/cmp /path/to/mirror
 
-Sync with Version Range
-=======================
+Sync with a Version Range
+=========================
 
-This command will download all versions of the ``example/cmp`` component to the specified path.
+This command downloads all versions of the ``example/cmp`` component to the specified path.
 
-To sync only specific versions of the component, specify the version range in the command:
+To sync only specific versions of the component, provide a version range:
 
 .. code:: shell
 
    compote registry sync --component "example/cmp>=1.0.0,<4.0.0" /path/to/mirror
 
-You can find the detailed version range syntax in the :ref:`version-range-specifications` section.
+You can find detailed version range syntax in the :ref:`version-range-specifications` section.
 
 Sync Only the Latest Version
 ============================
 
-To minimize the size of the mirror, you can sync only the latest version of the component:
+To minimize the mirror size, you can sync only the latest version of the component:
 
 .. code:: shell
 
    compote registry sync --component "example/cmp" --resolution latest /path/to/mirror
 
-This command will download only the latest version of the ``example/cmp`` component to the specified path.
+This command downloads only the most recent version of the ``example/cmp`` component to the specified path.
 
-Sync all Components Required by Project
-=======================================
+Sync All Components Required by a Project
+=========================================
 
-To sync all components required by a project, specify the project directory instead of the components:
+To sync all components required by a project, specify the project directory instead of individual components:
 
 .. code:: shell
 
    compote registry sync --project-dir /path/to/project /path/to/mirror
 
-To go through all the projects in the directory and sync the components required by each project, use the ``--recursive`` option:
+To scan all projects in a directory and sync the components required by each one, use the ``--recursive`` option:
 
 .. code:: shell
 
    compote registry sync --project-dir /path/to/parent_directory --recursive /path/to/mirror
 
-You can also use it with the ``--resolution latest`` option to sync only the latest versions of the components:
+You can also use it with the ``--resolution latest`` option to sync only the latest versions of each component:
 
 .. code:: shell
 
    compote registry sync --project-dir /path/to/parent_directory --recursive --resolution latest /path/to/mirror
 
 .. note::
 
-   You don't have to worry about components with different versions required by different projects when you're using ``--resolution latest``. The version solver will find the versions that satisfy the requirements of all the projects.
+   You don’t need to worry about components required in different versions by different projects when using ``--resolution latest``. The version solver will find versions that satisfy all project requirements.
 
-   For example, if project A requires ``example/cmp<3.1``, and project B requires ``example/cmp<4``, both versions ``3.0.3`` and ``3.3.9~1`` will be downloaded to the mirror to satisfy the requirements of both projects.
+   For example, if project A requires ``example/cmp<3.1`` and project B requires ``example/cmp<4``, then both versions ``3.0.3`` and ``3.3.9~1`` will be downloaded to the mirror to fulfill the dependencies.
 
 ***********************************************************
  Apply to Configuration File ``idf_component_manager.yml``
 ***********************************************************
 
-After the partial mirror is created, you can apply it to a profile in the :doc:`../reference/config_file` by adding the mirror URL to the ``local_storage_url`` field. For example, if your mirror is located at ``/opt/compote-mirror``, add the following to the configuration file:
+After creating the partial mirror, apply it to a profile in the :doc:`../reference/config_file` by adding the mirror URL to the ``local_storage_url`` field. For example, if your mirror is located at ``/opt/compote-mirror``, update the configuration file like this:
 
 .. code:: yaml
 
@@ -88,9 +88,9 @@ After the partial mirror is created, you can apply it to a profile in the :doc:`
        local_storage_url:
          - file:///opt/compote-mirror
 
-The version solver will look for the versions in the partial mirror before looking in the main mirror. For more information, see :ref:`url_precedence`.
+The version solver will check the versions in the partial mirror before looking in the main mirror. For more information, see :ref:`url_precedence`.
 
-You may also run a file server to serve the mirror. For example, to serve the mirror at ``http://localhost:9004``, add the following to the configuration file:
+You can also serve the mirror using a file server. For example, to serve it at ``http://localhost:9004``, update the configuration file as follows:
 
 .. code:: yaml
 

docs/en/guides/partial_mirror.rst

@@ -6,78 +6,83 @@ Users can authenticate into the ESP Component Registry using their GitHub accoun
 
 -  Upload and manage components in the registry
 -  Access the registry's API
--  Manage various access and permission settings
+-  Manage access and permission settings
 
-Roles are used to control access in the ESP Component Registry. They can be assigned at two levels:
+Roles are used to control access within the ESP Component Registry. They can be assigned at two levels:
 
-#. **Namespace Level** - Grants access and permissions within a particular namespace.
-#. **Component Level** - Grants more fine-grained control for individual components.
+#. **Namespace Level** – Grants access and permissions within a specific namespace.
+#. **Component Level** – Provides more fine-grained control over individual components.
 
 .. _what_is_namespace:
 
 **********************
  What Is a Namespace?
 **********************
 
-A *namespace* in the ESP Component Registry is a logical container for your components. By default, when you first log in using GitHub, you automatically get a namespace that matches your GitHub username. For example, if your GitHub username is `jdoe`, you will have a namespace named `jdoe` in the registry.
+A *namespace* in the ESP Component Registry is a logical container for your components. By default, when you first log in with GitHub, a namespace matching your GitHub username is automatically created. For example, if your GitHub username is `jdoe`, your namespace will be `jdoe`.
 
--  **Why use namespaces?** Namespaces keep your components organized and prevent naming collisions with components of other users. If two users want to create a component named `wifi-utilities`, having separate namespaces ensures that the components don't conflict.
--  **How to find or create namespaces?** The default namespace for each user is created automatically. Organizations or teams can request or create additional namespaces (for example, an organization might have a `my-company` namespace). See :ref:`namespace_requests` for more details on creating additional namespaces.
+-  **Why use namespaces?** Namespaces keep components organized and prevent naming collisions between different users. For instance, if two users create a component called `wifi-utilities`, namespaces ensure they don't conflict.
+-  **How to find or create namespaces?** Each user gets a default namespace automatically. Organizations or teams can request additional namespaces (e.g., a `my-company` namespace). See :ref:`namespace_requests` for more information.
 
 *****************
  Namespace Roles
 *****************
 
-When a user logs into the ESP Component Registry, they automatically gain access to the namespace that corresponds to their GitHub username. This means they can start uploading components and managing them under that namespace.
+When a user logs into the ESP Component Registry, they automatically gain access to their personal namespace (matching their GitHub username), allowing them to upload and manage components.
 
-If you want to grant access to your namespace to other users (e.g., collaborators), you can assign one of the following roles:
+To grant access to your namespace to other users (e.g., collaborators), assign them one of the following roles:
 
--  **owner** - Automatically assigned to the user who created the namespace. - Can manage components in the namespace - upload new component versions, yank and delete existing component versions - Can manage namespace roles for other users (assign, modify or revoke their roles).
--  **member** - Can manage components in the namespace - upload new component versions, yank and delete component versions
+-  **owner** – Automatically assigned to the creator of the namespace. - Can manage all components in the namespace. - Can upload new versions, yank, or delete components. - Can manage namespace roles for other users (assign, modify or revoke their roles).
+-  **member** – Can manage components in the namespace: - Can upload new versions, yank, and delete components.
 
 .. note::
 
-   Only a user with the **owner** role can assign or revoke roles from others at the namespace level.
+   Only a user with the **owner** role can assign or revoke roles at the namespace level.
 
 *****************
  Component Roles
 *****************
 
-While namespace roles apply to all components under a namespace, sometimes you need more granular control over a specific component. That's where **component roles** come in. By assigning roles at the component level, you can let others collaborate on a single component without giving them control over all components in your namespace.
+While namespace roles apply to all components within a namespace, component roles offer more granular control over individual components. That's where component roles come in. Assigning roles at the component level allows collaboration on specific components without granting broader access.
 
-The following component-level roles are available:
+Available component-level roles:
 
--  **maintainer** - Can manage all aspects of a single component - upload new versions, yank and delete existing versions - Managing component roles for other users - Useful when you want someone else to help maintain a component but not all components in your namespace.
--  **developer** - Can perform actions needed to develop a component - upload new versions, yank and delete existing versions
+-  **maintainer** – Full control over a single component. - Can upload, yank, or delete versions. - Can manage component roles for other users. - Useful for delegating control over a specific component.
+-  **developer** – Limited control. - Can upload new versions, yank, and delete existing versions.
 
 ***************************************
  Managing Roles in the Permissions Tab
 ***************************************
 
-You can manage roles for both your namespaces and components through the ESP Component Registry web interface. Navigate to the dropdown, and click on the **Permissions** tab. Here, you can:
+You can manage roles for both namespaces and components using the ESP Component Registry web interface. To access role management:
+
+#. Open the dropdown menu
+#. Click on the **Permissions** tab
+
+Here, you can:
 
 -  Create a request for a new namespace (see :ref:`namespace_requests`)
 -  View a list of all namespaces you have access to
 
-Clicking on a namespace name will lead you to the namespace's permissions page, where you can:
+Clicking a namespace name opens its permissions page, where you can:
 
 -  View a list of all users with roles in the namespace
 -  Assign or revoke roles for users in the namespace
 -  View a list of all components in the namespace
--  Click on a component name to view its permissions page
+-  Click a component name to open its permissions page
 
 On the component permissions page, you can:
 
--  View a list of all users with roles for the component
--  Assign or revoke roles for users for the component
+-  View a list of users and their roles for the component
+-  Assign or revoke roles for users at the component level
 
 .. _namespace_requests:
 
 Namespace Requests
 ==================
 
-If you need a namespace, which is not your default namespace (e.g., you want a namespace for your organization), you can request one by following these steps:
+If you need a namespace other than your default (e.g., for an organization), request one by following these steps:
 
 #. **Log in** to the ESP Component Registry using your GitHub account.
-#. **Navigate** to the **Permissions** tab.
-#. Fill in the **Request a new namespace** form with the name you want for your new namespace.
+#. **Go to** the **Permissions** tab.
+#. Fill out the **Request a new namespace** form with your desired namespace name.

docs/en/guides/roles.rst

@@ -6,15 +6,15 @@ To update the IDF Component Manager to the latest version, run the following com
 
 .. note::
 
-   If your version of ESP-IDF doesn't come with the IDF Component Manager, you can install it using the same commands.
+   If your version of ESP-IDF does not include the IDF Component Manager, you can install it using the same commands.
 
 .. tabs::
 
    .. group-tab::
 
       Windows
 
-      Run ``ESP-IDF PowerShell Environment`` or ``ESP-IDF Command Prompt (cmd.exe)`` from the Start menu and run the following command:
+      Open the ``ESP-IDF PowerShell Environment`` or ``ESP-IDF Command Prompt (cmd.exe)`` from the Start menu, then run:
 
       .. code:: powershell