Contribute to the Documentation

The pyiCub project is maintained across two GitHub repositories:

pyiCub: The main repository containing the Python interface and robot control logic.
pyiCub-doc: 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:

Write good docstrings in the pyiCub repository using the Sphinx format.
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.
The pyiCub-doc project is connected to ReadTheDocs, which: - Automatically builds and publishes the updated documentation online.

Sphinx Docstring Template for contributing code:

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.):

Clone the `pyiCub-doc` repository:

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

Add or update .rst files inside the appropriate folders like:
```
- design/
- development/
- contributions/
```
Follow the Sphinx format for headings, code blocks, and links.

Commit and push your changes:

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:

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