Contribute to the Documentation
======================================

The `pyiCub` project is maintained across two GitHub repositories:

- `pyiCub <https://github.com/s4hri/pyicub>`_: The main repository containing the Python interface and robot control logic.
- `pyiCub-doc <https://github.com/Mohammad-Gharb/pyiCub-doc/blob/main/source/api/pyicub.rst>`_: This repository contains all documentation, including:

  - Getting Started
  - System Design
  - API Reference (autogenerated)
  - Development
  - Contribution Guidelines

Documentation is built using **Sphinx** and hosted on **Read the Docs**.

Automated API Documentation
----------------------------

The API reference is automatically generated from the `pyiCub` codebase. Here's how it works:

1. **Write good docstrings** in the `pyiCub` repository using the Sphinx format.
2. When you **push a commit** to the `pyiCub` repo:
   - A **GitHub Action** will regenerate the API documentation and push changes to the `pyiCub-doc` repository.
3. The `pyiCub-doc` project is connected to **ReadTheDocs**, which:
   - Automatically builds and publishes the updated documentation online.

**Sphinx Docstring Template** for contributing code:

.. code-block:: python

    def example_function(param1: int, param2: str) -> bool:
        """Brief description of what the function does."""

        :param param1: Description of the first parameter.
        :type param1: int
        :param param2: Description of the second parameter.
        :type param2: str
        :return: Description of the return value.
        :rtype: bool

Manual Contributions (System Design, Guidelines, etc.)
------------------------------------------------------

To contribute to the rest of the documentation (design, how-to guides, contribution workflow, etc.):

1. **Clone the `pyiCub-doc` repository**:

   .. code-block:: bash

      git clone https://github.com/s4hri/pyicub-doc.git
      cd pyicub-doc

2. **Add or update** `.rst` files inside the appropriate folders like:

   .. code-block:: text

      - design/
      - development/
      - contributions/

3. **Follow the Sphinx format** for headings, code blocks, and links.

4. **Commit and push your changes**:

   .. code-block:: bash

      git add .
      git commit -m "Add/update documentation"
      git push origin <your-branch>

Once changes are pushed to the ``main`` branch (or another branch tracked by ReadTheDocs), the documentation site will be automatically rebuilt and published.

Need Help?
----------


Check out:

- `Sphinx reStructuredText syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
- `Read the Docs guide <https://docs.readthedocs.io/en/stable/>`_

We welcome your contributions to make the documentation clearer and more complete!